Yii-ses-feedback

Introduction

Does your Yii application use Amazon Simple Email Service (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 (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.
• 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.
  2. Create an Amazon SNS topic named bounces_and_complaints-topic.
  3. Configure the new Amazon SNS topic to publish to the SQS queue.
  4. 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 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
return array(
    'import' => 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
return array(
    // ...
    'components'=>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.

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
return array(
    // ...
    'components'=>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
return array(
    // ...
    'import' => 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
return array(
    // ...
    'components'=>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
class PPHSesFeedbackCommand extends ASesFeedbackCommand
{
    /**
     * Initialize the command object so we can attach listeners to the parent Object events
     */
    public function init()
    {
        parent::init();

        // Attach the reactToBounce() method to the onSesBounce event.
        Yii::app()->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. 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