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
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
License
The MIT License (MIT). Please see License File for more information.
Laravel Package Boilerplate
This package was generated using the Laravel Package Boilerplate.