Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/peopleperhour/yii-ses-feedback
Process SES feedback notifications so that your Yii app can react to Email Bounces and Complaints
https://github.com/peopleperhour/yii-ses-feedback
Last synced: 24 days ago
JSON representation
Process SES feedback notifications so that your Yii app can react to Email Bounces and Complaints
- Host: GitHub
- URL: https://github.com/peopleperhour/yii-ses-feedback
- Owner: PeoplePerHour
- License: mit
- Created: 2013-10-25T18:30:25.000Z (about 11 years ago)
- Default Branch: master
- Last Pushed: 2016-07-28T11:13:01.000Z (over 8 years ago)
- Last Synced: 2024-03-26T19:28:45.170Z (8 months ago)
- Language: PHP
- Size: 21.5 KB
- Stars: 3
- Watchers: 6
- Forks: 2
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
Yii-ses-feedback
================
Introduction
------------
Does your Yii application use Amazon [Simple Email Service (SES)](http://aws.amazon.com/ses/) for sending email?
If so you can use this extension to process "feedback notifications" such as email bounces and email complaints.
* What do we mean by a "email bounce"? We mean a email delivery failure, for example, if an email address does not exist.
* What do we mean by a "email complaint"? We mean the recipient has indicated they do not what the email that you sent them, for example, by clicking "Mark as spam" in their email client.
Amazon SES has feedback loops set up with certain major ISPs, and can automatically forward the complaint information to the sender.
Why do you need Yii-ses-feedback?
---------------------------------
* Cost: By using SES, you pay per message. To save money you need a feedback loop so you can know which emails are not being recieved, and stop sending them.
* Reputation: If your SES account racks up too many bounces or complaints, your reputation will decrease. Amazon might not let you increase your sending throughput for example.
* Workflow: You might want to deactivate users with invalid email addresses. For many apps, having a large number of dormant user accounts will we a performance problem.
* Stats: You might want to record bounce stats in your application database.
Requirements
------------
* Yii 1.*
* You must be using Amazon [Simple Email Service](http://aws.amazon.com/ses/) (SES) to send email.
* You must configure Amazon SES Feedback Notifications via Amazon Simple Notification Service (SNS).
This can be done via there web-console - here are [instructions](http://docs.aws.amazon.com/ses/latest/DeveloperGuide/configure-sns-notifications.html).
* You must configure the SNS messages to integrate with Amazon Simple Queue Service (SQS) to ensure the feedback notifications are stored until our application can process them.
Set up the following AWS components to handle bounce notifications:
1. Create an Amazon SQS queue named `bounces_and_complaints`.
1. Create an Amazon SNS topic named `bounces_and_complaints-topic`.
1. Configure the new Amazon SNS topic to publish to the SQS queue.
1. Configure Amazon SES to publish bounce notifications using `bounces_and_complaints-topic` to the `bounces_and_complaints` queue. Instead of a combined queue, you can choose to use two separate queues if you want.
* Yii-ses-feedback requires the [AWS SDK for PHP](https://github.com/aws/aws-sdk-php) to access the SQS API. SQS API access credentials will be needed when configuring Yii-ses-feedback.
* Yii-ses-feedback supports v2 or v3 of the API. v3 was released in 27/May/15 and is the default, if you need v2 then there is one extra line to add to the config, see below.
Features
--------
* Instead of parsing bounced emails ourselves to determine the cause, we can let Amazon SES do it for us.
Amazon SES will categorize your hard bounces into two types: permanent and transient.
A permanent bounce indicates that you should never send to that recipient again.
A transient bounce indicates that the recipient's ISP is not accepting messages for that particular recipient at that time and you can retry delivery in the future.
The amount of time you should wait before resending to the address that generated the transient bounce depends on the transient bounce type.
Certain transient bounces require manual intervention before the message can be delivered (e.g., message too large or content error).
If the bounce type is undetermined, you should manually review the bounce and act accordingly.
* Raise a Yii event whenever a Email bounce or complaint is found.
It's up to you how you handle the event (an example is given).
Installation - Manual (The Old Fashion Way)
-------------------------------------------
Extract the package to your `extensions` folder into a directory called `yii-ses-feedback`.
Ensure the extension files will be autoloaded by adding a line to the Yii imports config section:
```php
array(
// ...
'ext.yii-ses-feedback.*',
),
```
Add the component to your Yii console app config file (e.g. `your-project/protected/config/console.php`) and define each queue.
If you have multiple queues, configure multiple handlers.
```php
array(
// ...
'sesFeedback' => array(
'class' => 'ext.yii-ses-feedback.ASesFeedback',
'handlers' => array(
'bounceAndComplaint' => array(
'class' => 'ext.yii-ses-feedback.ASesFeedbackHandler',
'accessKey' => 'DKIASHFUSET2X3G5JR5D',
'secretKey' => 'thisisadummycred+ZNty4Ag4eig453yOfFuffr4',
'region' => 'us-east-1',
'queueName' => 'bounces_and_complaints',
// 'awsApiVersion' => 2, // By default version 3 of the AWS SDK is used, uncomment this is your app uses v2.
),
)
),
// ...
),
// ...
);
```
Now we need a way to trigger the command. Copy the `examples/ExampleSesFeedbackCommand.php` file into your `commands` folder and modify it as you need for your application.
Installation - Automatic (using Composer)
-----------------------------------------
The advantage of using composer is that you wont need to change your Yii import map, the composer autoloader will import the needed files.
Add `peopleperhour/yii-ses-feedback` as a dependency in your project's `composer.json` file:
{
"require": {
...
"peopleperhour/yii-ses-feedback": "dev-master"
},
Download and install Composer.
curl -s "http://getcomposer.org/installer" | php
Install your dependencies.
php composer.phar update
Require Composer's autoloader. Composer prepares an autoload file that's capable of autoloading all of the classes in any of the libraries that it downloads.
To use it, just add the following line to your code's bootstrap process.
require '/path/to/vendor/autoload.php';
You can find out more on how to install Composer, configure autoloading, and other best-practices for defining dependencies at [getcomposer.org](http://getcomposer.org/).
To configure the extension, add a `sesFeedback` component to your Yii console app config file (e.g. `your-project/protected/config/console.php`) and define each queue.
If you have multiple queues, configure multiple handlers.
```php
array(
// ...
'sesFeedback' => array(
'class' => '\ASesFeedback', // Composer autoloading needs to a prepended backslash
'handlers' => array(
'bounceAndComplaint' => array(
'class' => '\ASesFeedbackHandler', // Composer autoloading needs to a prepended backslash
'accessKey' => 'DKIASHFUSET2X3G5JR5D',
'secretKey' => 'thisisadummycred+ZNty4Ag4eig453yOfFuffr4',
'region' => 'us-east-1',
'queueName' => 'bounces_and_complaints',
// 'awsApiVersion' => 2, // By default version 3 of the AWS SDK is used, uncomment this is your app uses v2.
),
)
),
// ...
),
// ...
);
```
Running unit tests
------------------
The unit tests do not use a real SQS queue, instead they use a Mock queue implemented as a PHP Array.
In your `tests/config.php` file, ensure the extension files will be imported and that the sesFeedback component uses the Mock Version.
If installed into the Yii extensions folder:
```php
array(
// ...
'application.extensions.yii-ses-feedback.*', // Not needed if using composer auto-loader
),
// ...
'components'=>array(
// ...
'sesFeedback' => array(
'class' => 'ext.yii-ses-feedback.ASesFeedback', // or '\ASesFeedback' if using the composer autoloader.
'handlers' => array(
'myMockQueue' => array(
'class' => 'ext.yii-ses-feedback.tests.mocks.ASesFeedbackHandlerMock', // or '\ASesFeedbackHandlerMock'
),
)
),
),
);
```
If installed via composer:
```php
array(
// ...
'sesFeedback' => array(
'class' => '\ASesFeedback', // or 'application.vendor.peopleperhour.yii-ses-feedback.ASesFeedback'
'handlers' => array(
'myMockQueue' => array(
'class' => '\ASesFeedbackHandlerMock', // or 'application.vendor.peopleperhour.yii-ses-feedback.tests.mocks.ASesFeedbackHandlerMock'
),
)
),
),
);
```
Go to your application tests directory, usually `protected/tests` and run the following command:
phpunit --verbose ../extensions/yii-ses-feedback/tests/unit/
or
phpunit --verbose ../vendor/peopleperhour/yii-ses-feedback/tests/unit/
This will run the unit tests, if all went well they should all pass, otherwise please check your configuration.
Example Usage
-------------
Yii-ses-feedback itself doesn't do anything except raise Yii events.
To do something useful with email feedback, you'll need to attach event listeners on the `onSesBounce` and `onSesComplaint` events .
To do this, create a yiic command that `extends ASesFeedbackCommand`, here's an example where complaints are logged and bounces are saved to the database:
```php
sesFeedback->onSesBounce = array($this, "reactToBounce");
// Attach an anonymous function to the onSesComplaint event.
// If we decide we want to do something when someone complains, add it here
Yii::app()->sesFeedback->onSesComplaint = function ($event) {Yii::log('Complaint recieved in PPHSesFeedbackCommand - No action taken.', CLogger::LEVEL_INFO, ASesFeedbackCommand::LOGCAT);};
}
/**
* Process a Email bounce event.
*/
public function reactToBounce(CEvent $event)
{
// Add your custom logic here
$msg = $event->params['msg'];
// Extract the reason for the bounce
$reason = 'bounceType: '.$msg['bounce']['bounceType'].'. ' // e.g. 'Permanent' or 'Transient'.
.'bounceSubType: '.$msg['bounce']['bounceSubType'].'.';// e.g. 'Undetermined','General','Suppressed','NoEmail','MailboxFull','MessageToolarge','ContentRejected','AttachmentRejected'
foreach($msg['bounce']['bouncedRecipients'] as $r) {
$email = $r['emailAddress'];
// If this bounce notification has a delivery status notification (DSN), fetch it:
if (isset($r['diagnosticCode'])) {
$reason .= ' diagnosticCode: '.$r['diagnosticCode'];
}
// Add a new bounce record to the database
EmailBounce::model()->addNewBounce(
$email,
substr($msg['bounce']['bounceType'],0,5),
$reason,
date('Y-m-d H:i:s', strtotime($msg['mail']['timestamp']))
);
}
}
}
```
How to schedule automatic processing
------------------------------------
To automatically process your feedback queue periodically, set up a cron job to run the command. Example:
17 3 * * * /usr/bin/php /var/www/yourapp/yiic.php exampleSesFeedback >/dev/null 2>&1
Another way is to use the Yii [phpdoc-crontab extension](http://www.yiiframework.com/extension/phpdoc-crontab/).
Once configured, you will be able to define automated Yii commands with some simple PHP header comments.
Here's an Example which could be added to the `PPHSesFeedbackCommand` class above:
/**
* Fetch feedback notifications from SQS and process them.
*
* @cron *\10 * * * *
* @cron-tags live staging
*/
public function actionIndex($maxNum=1000,$leaveFailuresInQueue=false)
{
return parent::actionIndex($maxNum,$leaveFailuresInQueue);
}
Resources
---------
* Instructions to configure SNS notifications - http://docs.aws.amazon.com/ses/latest/DeveloperGuide/configure-sns-notifications.html
* AWS SDK PHP 3: http://docs.aws.amazon.com/aws-sdk-php/v3/guide/
* or AWS SDK PHP 2 for SQS: http://docs.aws.amazon.com/aws-sdk-php-2/guide/latest/service-sqs.html