Laravel SES complaints and bounces manager

This package listens to AWS SNS notifications and stops sending mail to email addresses that have received a permanent bounced notification or users who have marked an email as spam.

How it works

This package intercepts each mail sent by your laravel application and check if the receiver has not marked your mail as SPAM or if the user email address received a permanent bounce notification from AWS SNS before. And according to your strategy defined in the config file, it stops the email sending process or sends the email.

Installation

Before the installation process, please refer to the version mapping table below to ascertain compatibility between laravel-ses-complaints package version and your Laravel application:

| Package Version | Laravel Version | |-----------------|-----------------| | v1.0.0 | 9 & 10 | | v0.0.4 | 9 | | v0.0.3 | 9 | | v0.0.2 | 8 |

Ensure you select the appropriate version that corresponds with your Laravel version to guarantee full functionality and compatibility.

You can install the package via composer:

composer require oza75/laravel-ses-complaints

Publish migrations files and config file

php artisan vendor:publish --provider="Oza75\LaravelSesComplaints\LaravelSesComplaintsServiceProvider"

Run migration

php artisan migrate

This command will create 2 tables in your database. sns_subscriptions table for sns subscription confirmation request and ses_notifications table to store complaint and bounce notifications received from SNS.

Usage

Create SNS topics

Go to your AWS SNS console and create two HTTP/S topic with these endpoints:

• https://yourapp.tld/aws/sns/ses/bounces listen to bounce notifications
• https://yourapp.tld/aws/sns/ses/complaints listen to complaint notifications

These endpoints can be customized in the config file. Note that as soon as you create these endpoints, they will be automatically confirmed. If not, you can use php artisan aws:sns:subscribe-url command to print out the SubscribeURL required to confirm subscription directly in your aws console. More details

Create SNS topics

Add SNS topics to your SES domain. More details

Config file

<?php

return [
    /**
     * If enabled is set to true, this package will intercept each mail then check
     * if the mail passes all middlewares defined in this config file. It will also
     * listen to sns notifications and store them in database. You may set enabled to false
     * to completed disabled this package
     */
    'enabled' => true,
    /*
     * Models used to created a new subscription confirmation request and
     * to store a sns notification received from aws.
     */
    'models' => [
        'subscription' => \Oza75\LaravelSesComplaints\Models\Subscription::class,
        'notification' => \Oza75\LaravelSesComplaints\Models\Notification::class,
    ],

    /**
     * Routes used to handle bounces notification and complaints notifications
     */
    'routes' => [
        'bounces' => '/aws/sns/ses/bounces',
        'complaints' => '/aws/sns/ses/complaints',
    ],

    // Controller used to handle all actions. You can override this if you want to add
    // more specific logic
    'controller' => \Oza75\LaravelSesComplaints\Controllers\SNSController::class,

    /**
     * An array of middleware that the email will go through. If only one return false
     * we do not send the email. All middlewares must implement the \Oza75\LaravelSesComplaints\Contracts\CheckMiddleware::class
     * interface.
     */
    'middlewares' => [
        \Oza75\LaravelSesComplaints\Middlewares\ComplaintCheckMiddleware::class => [
            /**
             * The max number of sns complaint notification before stop sending email to the user
             */
            'max_entries' => 1,
            /**
             * If the check_by_subject is set to true, we will count
             * the amount of complaint notification  received from sns and that has the same subject as
             * the email we are trying to send. If the count is greater or equal to max_entry we don't send
             * the email.
             */
            'check_by_subject' => true,
        ],
        \Oza75\LaravelSesComplaints\Middlewares\BounceCheckMiddleware::class => [
            /**
             * The max number of sns bounced notification before stop sending email to the user
             */
            'max_entries' => 3,
            /**
             * If the check_by_subject is set to true, we will count
             * the amount of bounced notification  received from sns and that has the same subject as
             * the email we are trying to send. If the count is greater or equal to max_entry we don't send
             * the email.
             */
            'check_by_subject' => false,
        ]
    ],
];

Testing

composer test

Changelog

Please see CHANGELOG for more information what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security

If you discover any security related issues, please email [email protected] instead of using the issue tracker.

Credits

• Aboubacar OUATTARA
• All Contributors

License

The MIT License (MIT). Please see License File for more information.

Laravel Package Boilerplate

This package was generated using the Laravel Package Boilerplate.