PHPackages antonbelous/laravel-ses-tracking - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [HTTP & Networking](/categories/http) 4. / 5. antonbelous/laravel-ses-tracking ActiveLibrary[HTTP & Networking](/categories/http) antonbelous/laravel-ses-tracking ================================ A Laravel artisan based package to create the AWS (SES + SNS) infrastructure to receive email event notifications with Http/Https endpoint. v1.0.0(1y ago)02MITPHPPHP ^8.2 Since Apr 24Pushed 1y agoCompare [ Source](https://github.com/AntonBelousGit/laravel-ses-tracking)[ Packagist](https://packagist.org/packages/antonbelous/laravel-ses-tracking)[ Docs](https://github.com/antonbelous/laravel-ses-tracking)[ RSS](/packages/antonbelous-laravel-ses-tracking/feed)WikiDiscussions main Synced 1mo ago READMEChangelog (1)Dependencies (5)Versions (2)Used By (0) Laravel SES Tracking ==================== [](#laravel-ses-tracking) [![Latest Stable Version](https://camo.githubusercontent.com/0fb4c3b4b89dff6b0b2916aef12b17501458a9a6bdc145f5608e3a1385672787/687474703a2f2f706f7365722e707567782e6f72672f616b68616e3631392f6c61726176656c2d7365732d747261636b696e672f763f7374796c653d666c61742d737175617265)](https://packagist.org/packages/akhan619/laravel-ses-tracking)[![Tests](https://github.com/akhan619/laravel-ses-tracking/actions/workflows/test.yml/badge.svg?branch=main)](https://github.com/akhan619/laravel-ses-tracking/actions/workflows/test.yml/badge.svg?branch=main)[![PHP Version Require](https://camo.githubusercontent.com/ec2f054bc38ef69f440f246d5ed3529062415e85810fe7783850ffee262961de/687474703a2f2f706f7365722e707567782e6f72672f616b68616e3631392f6c61726176656c2d7365732d747261636b696e672f726571756972652f7068703f7374796c653d666c61742d737175617265)](https://packagist.org/packages/akhan619/laravel-ses-tracking)[![Total Downloads](https://camo.githubusercontent.com/89afc02ade83978ae53d922da1a1d5f32f348ac108d0386c22742b2cc889bf1c/687474703a2f2f706f7365722e707567782e6f72672f616b68616e3631392f6c61726176656c2d7365732d747261636b696e672f646f776e6c6f6164733f7374796c653d666c61742d737175617265)](https://packagist.org/packages/akhan619/laravel-ses-tracking)[![StyleCI](https://camo.githubusercontent.com/a86af56575768899e93128537e5874e2c43ac981812226e63efec51378089744/68747470733a2f2f6769746875622e7374796c6563692e696f2f7265706f732f3438303138323236332f736869656c643f6272616e63683d6d61696e267374796c653d666c61742d737175617265)](https://github.styleci.io/repos/480182263?branch=main)[![License](https://camo.githubusercontent.com/79c07926cc650796645eec788ad823f0c2266d6450f5d8ff82e487d4f330c193/687474703a2f2f706f7365722e707567782e6f72672f616b68616e3631392f6c61726176656c2d7365732d747261636b696e672f6c6963656e73653f7374796c653d666c61742d737175617265)](https://packagist.org/packages/akhan619/laravel-ses-tracking) Setup the AWS infrastructure to handle email events using SES/SNS and http/s endpoints with a single Laravel artisan command. This package is unopinionated in the sense that every setting can be changed as per your requirements. It follows an interactive CLI based setup process so that you know exactly what will be configured. Also, includes a debug mode where you can see all the settings and configurations that will be used without actually making the API calls. Finally, it can be very painful to clean up the AWS resources when an API call fails. For example, if you are trying to enable some advanced filter policy for an endpoint, only for that setting to fail, then you might have to go back and remove the configuration sets and SNS topics manually. To tackle the issue, the package will automatically try and revert any changes made to the AWS infrastructure when any exceptions occur. What this package does ---------------------- [](#what-this-package-does) As mentioned this package automates the process of: - Setting up the SES configuration set. - Setting up a SNS Topic. - Setting up the event destinations for the configuration set. - Subscribing the http/s endpoints to the SNS topic. What this package doesn't do ---------------------------- [](#what-this-package-doesnt-do) The package will not do anything beyond what is mentioned above. So, the package won't: - Add the created configuration set to your SES driver. - Manage the https/s subscription confirmation or actual processing of event messages from SNS. - Create the domains or endpoints with a Laravel project running (but won't that be awesome 😃 ). If you are looking for a package that will manage the incoming `SES` notifications and track email events then you may look at the [Laravel Ses Event Manager](https://github.com/akhan619/laravel-ses-event-manager) package. The `Laravel Ses Event Manager` package integrates nicely with this package and handles the processing and storage of email event notifications sent to the webhooks. > **FULL DISCLOSURE**: I am the author of the `Laravel Ses Event Manager` package. Laravel and PHP Versions ======================== [](#laravel-and-php-versions) The package is written for Laravel 9 and Php 8 and above. Overview of SES/SNS Event Notification Process ============================================== [](#overview-of-sessns-event-notification-process) To understand the process of setting up event notifications for emails on AWS we must know the 2 key objects that will need to be set up on these services: - Configuration Set (`SES`) - Topic (`SNS`) To receive notifications for emails on our http/s endpoints we first need to set up a `Configuration Set` on `SES`. The `Configuration Set` is used with the `ses` driver on Laravel. This tells `AWS` that we wish to send email event notifications to some listener. The '`some listener`' in our case will be a `SNS` topic. This is specified by creating `Event Destinations`. An `Event Destination` serves 2 purposes: - It specifies which events to send notifications for. - It specifies where to send the event notifications. Since we want to use `SNS` topics, we next need a `SNS` topic. The `SNS` topic receives event notifications from `SES`. When `SNS` receives a notification it will send a message to all the `subscribers` listening on the topic. In this case the `subscriber` will be a `http/s` endpoint. So we need to create 4 objects: - Configuration Set - Event Destination (Part of a configuration set) - Topic - Subscription (Subscribes to a topic) This a brief overview of what needs to be setup in order to enable http/s endpoints to receive email event notifications. Installation ============ [](#installation) Via Composer ``` $ composer require akhan619/laravel-ses-tracking ``` > This package uses Laravel's package auto-discovery so there is no need to add the service provider in config/app.php Configuration File You can publish the configuration file using the following artisan command: ``` $ php artisan vendor:publish --provider="Akhan619\LaravelSesTracking\LaravelSesTrackingServiceProvider" --tag="config" ``` This is will publish a new configuration file called `laravel-ses-tracking.php` in the `config` folder. Usage ===== [](#usage) Debug Mode ---------- [](#debug-mode) The package is configured by default to run in `debug mode`. This means that when you run the setup command, the package will show you all the configuration options that will be used for the actuall API calls including routes/topics/subscriptions etc. Debug mode can be turned off by setting `debug => FALSE` in the config. > No API calls are made in debug mode. So you can test out the different configuration possibilities without making any changes to your AWS resources. Setup ----- [](#setup) Run the following command and follow the interactive steps. ``` $ php artisan SesTracking:setup ``` You will have to confirm: - The Route names that will be used as endpoints. - The Topic names for SNS. - The Event Destination Names for SES. Once you confirm all 3, the package will create and subscribe the endpoints to the SNS Topic. The `SubscriptionArns` will be printed to the console on Success. They will show `pending confirmation` unless you enable `ReturnSubscriptionArn` in the configuration. Example Run ----------- [](#example-run) [![An example to show the console steps and output on a succesful run of the setup command.](./assets/images/success.jpg "Successful Run")](./assets/images/success.jpg) Confirming Subscription ----------------------- [](#confirming-subscription) You will need to set up the code on the actual endpoint service yourself to confirm subscription. Currently, you have 72 hours before the subscriptions expire to confirm the subscription. You may resend the confirmation message from the `AWS console`. Configuration ============= [](#configuration) AWS Credentials --------------- [](#aws-credentials) AWS credentials are picked up from the .env file ``` AWS_ACCESS_KEY_ID= AWS_SECRET_ACCESS_KEY= AWS_DEFAULT_REGION= ``` If you wish to use a different set of credentials then specify them in the configuration file under the `ses` key. ``` 'ses' => [ 'key' => env('AWS_ACCESS_KEY_ID'), 'secret' => env('AWS_SECRET_ACCESS_KEY'), 'region' => env('AWS_DEFAULT_REGION'), ], ``` > Note: The AWS credentials must have permissions that allow > > - Creation of SES Configuration Sets > - Creation of SNS Topics > - Creation of SES Event Destinations > - Subscribing an http/s Endpoint to a SNS Topic > > Since this is a topic in itself, please refer to the AWS docs to see what permissions need to be setup. SNS Protocol ------------ [](#sns-protocol) Currently, 2 SNS protocols are supported `http/https`. The default is `https`. You may change the protocol under the `subscriber` key by setting one of them to `true`: ``` 'subscriber' => [ 'http' => FALSE, 'https' => TRUE, ], ``` Domain and Scheme ----------------- [](#domain-and-scheme) By default, the package picks up the `domain` and `scheme` to use for the endpoint from the `APP_URL` in the `.env` file. If you wish to use a different endpoint than the project url, specify the values under the corresponding keys in the config file: ``` 'domain' => null, // If null the domain will be pulled from APP_URL. ``` ``` 'scheme' => null, // If null the scheme will be pulled from APP_URL. ``` > Note: The scheme must match the subscriber SNS protocol, when using http/s subscribers. Events ------ [](#events) You may specify exactly which email events that you want to listen to by setting the event to `true` in the `active` key: ``` 'active' => [ 'sends' => TRUE, 'rendering_failures' => TRUE, 'rejects' => FALSE, 'deliveries' => FALSE, 'bounces' => TRUE, 'complaints' => FALSE, 'delivery_delays' => FALSE, 'subscriptions' => FALSE, 'opens' => FALSE, 'clicks' => FALSE, ], ``` Routes ------ [](#routes) Routes are customizable for each event by specifying values for the `route_prefix` and the `routes` key: ``` 'route_prefix' => 'email/notification', // Set to null if no prefix is required. ``` ``` 'routes' => [ 'sends' => 'sends', 'rendering_failures' => 'rendering-failures', 'rejects' => 'rejects', 'deliveries' => 'deliveries', 'bounces' => 'bounces', 'complaints' => 'complaints', 'delivery_delays' => 'delivery-delays', 'subscriptions' => 'subscriptions', 'opens' => 'opens', 'clicks' => 'clicks', ], ``` The actual endpoint is then generated seperately for each event as: ``` scheme://domain/route_prefix/route ``` > Note: Routing endpoints are generated and subscribed only for the events that are enabled. Route Confirmation ------------------ [](#route-confirmation) When you run the setup command, the package will output to the console the http/s endpoints that will be configured on AWS (when running in Live mode user will be requested to confirm the routes). This allows you to make sure the endpoints are exactly as you want. The output looks like (*based on a fresh laravel project with default values*): EventRoute NamesendsdeliveriesbouncesConfiguration Set ----------------- [](#configuration-set) The package creates a `Configuration Set` in `SES` that you may use with the emails that you want event notifications for. All the options that are available on the `AWS Console` can be set through the configuration file: ``` 'configuration_set' => [ 'ConfigurationSetName' => 'ses-event', 'DeliveryOptions' => [ 'SendingPoolName' => null, 'TlsPolicy' => 'REQUIRE', ], 'ReputationOptions' => [ 'LastFreshStart' => null, 'ReputationMetricsEnabled' => FALSE, ], 'SendingOptions' => [ 'SendingEnabled' => TRUE, ], 'SuppressionOptions' => [ 'SuppressedReasons' => [], ], 'Tags' => [], 'TrackingOptions' => [ 'CustomRedirectDomain' => null, ], ], ``` > Note: Some of the options here when enabled are charged seperately by `AWS`. You should check the defaults set here for your use case. Please refer to the `AWS docs` for how to set these options and what impact they have. SNS Topics ---------- [](#sns-topics) Similar to route names, the topic name that is generated for every event can be modified by changing the `topic_name_prefix` , `topic_name_suffix` and the `topic_name` keys in the config as below: ``` 'topic_name_prefix' => env('APP_NAME', 'local'), // Set to null if no prefix is required. ``` ``` 'topic_names' => [ 'sends' => 'sends', 'rendering_failures' => 'rendering-failures', 'rejects' => 'rejects', 'deliveries' => 'deliveries', 'bounces' => 'bounces', 'complaints' => 'complaints', 'delivery_delays' => 'delivery-delays', 'subscriptions' => 'subscriptions', 'opens' => 'opens', 'clicks' => 'clicks', ], ``` ``` 'topic_name_suffix' => 'us-east-1', // Set to null if no prefix is required. ``` SNS Topic Configuration ----------------------- [](#sns-topic-configuration) When creating a SNS topic, there are other options that can be set besides the name. For example you may want to enable at-rest encryption for the payload or define a delivery retries policies. These can be specificied under the key `sns_topic_configuration_data` in the config file. Please refer to the `AWS docs` to see how to set them properly. ``` 'DeliveryPolicy' => [], 'Policy' => [], 'KmsMasterKeyId' => null, 'Tags' => [], ``` SNS Topic Names Confirmation ---------------------------- [](#sns-topic-names-confirmation) When you run the setup command, the package will output to the console the SNS topics that will be configured on AWS (when running in Live mode user will be requested to confirm the topic names). This allows you to make sure the topic names are exactly as you want. The output looks like (*based on a fresh laravel project with default values*): EventTopic NamesendsLaravel-sends-us-east-1deliveriesLaravel-deliveries-us-east-1bouncesLaravel-bounces-us-east-1Event Destination Names ----------------------- [](#event-destination-names) Just like before, event destination names can be customized on a per event basis by changing the self-explantory config options below: ``` 'event_destination_prefix' => 'destination', ``` ``` 'destination_names' => [ 'sends' => 'sns', 'rendering_failures' => 'sns', 'rejects' => 'sns', 'deliveries' => 'sns', 'bounces' => 'sns', 'complaints' => 'sns', 'delivery_delays' => 'sns', 'subscriptions' => 'sns', 'opens' => 'sns', 'clicks' => 'sns', ], ``` ``` 'event_destination_suffix' => 'us-east-1', ``` If instead, you want to attach the Topic names as a suffix for the event destinations, to help with tracking, then set the following option to `TRUE`. ``` 'topic_name_as_suffix' => TRUE, ``` Setting this to `TRUE` disables the `event_destination_suffix`. Event Destination Names Confirmation ------------------------------------ [](#event-destination-names-confirmation) When you run the setup command, the package will output to the console the SES Event Destination names that will be configured on AWS (when running in Live mode user will be requested to confirm the destination names). This allows you to make sure the destination names are exactly as you want. The output looks like (*based on a fresh laravel project with default values*): EventEvent Destination Namesendsdestination-sns-Laravel-sends-us-east-1deliveriesdestination-sns-Laravel-deliveries-us-east-1bouncesdestination-sns-Laravel-bounces-us-east-1Subscription Configuration -------------------------- [](#subscription-configuration) You may specify additional options when subscribing an endpoint to a `SNS` Topic under the `sns_subscription_configuration_data` key in the config file. Currently you can set the following options: ``` 'ReturnSubscriptionArn' => false, ``` ``` 'DeliveryPolicy' => [], ``` ``` 'FilterPolicy ' => [], ``` ``` 'RawMessageDelivery' => 'false', ``` ``` 'RedrivePolicy' => null, ``` Please refer to `AWS docs` for further details on how to use these settings. Rollback on Failure =================== [](#rollback-on-failure) Making API calls always entail failure possibility. So every configuration setting is extensively validated before making the calls. Still, API calls can fail. Maybe, the `topic name` already exists. Since this is a multi-step process, you maybe left with wasted resources that you would have to go and clear yourself. So the package tries to roll back to a clean state. This means it will delete the `Configurations Set` and/or the `Topic` that was created on a failure of the succeding steps. This should be enough for most cases. But, it might be that the call to delete these resources themselves fail. In that case, a manual clean-up is required sadly. > If you are in this boat then as a consoloation, this developer had to manually clean up many times while this package was being developed. Change log ---------- [](#change-log) Please see the [changelog](changelog.md) for more information on what has changed recently. Testing ------- [](#testing) Run the tests with ``` $ composer test ``` RoadMap ------- [](#roadmap) - Add tests!!! - Add a option to the command to answer yes to all confirmations. - Add a seperate command to delete the AWS resources that were created. A way for users to test and clear AWS resources. - Add other protocols such as SQS. Contributing ------------ [](#contributing) Please see [contributing.md](contributing.md) for details and a todolist. Security -------- [](#security) If you discover any security related issues, please email instead of using the issue tracker. Credits ------- [](#credits) - Aman Khan License ------- [](#license) MIT. Please see the [license file](license.md) for more information. ### Health Score 29 — LowBetter than 60% of packages Maintenance48 Moderate activity, may be stable Popularity2 Limited adoption so far Community10 Small or concentrated contributor base Maturity49 Maturing project, gaining track record Bus Factor1 Top contributor holds 50% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Unknown Total 1 Last Release 384d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/68ba3420deb612a376caf1524e3cb4373ccb58e22b643ae6e8d439ea4eeb9a10?d=identicon)[AntonBelousGit](/maintainers/AntonBelousGit) --- Top Contributors [![akhan619](https://avatars.githubusercontent.com/u/73259168?v=4)](https://github.com/akhan619 "akhan619 (6 commits)")[![StyleCIBot](https://avatars.githubusercontent.com/u/11048387?v=4)](https://github.com/StyleCIBot "StyleCIBot (4 commits)")[![AntonBilousCode](https://avatars.githubusercontent.com/u/85167575?v=4)](https://github.com/AntonBilousCode "AntonBilousCode (1 commits)")[![ProjektGopher](https://avatars.githubusercontent.com/u/1688608?v=4)](https://github.com/ProjektGopher "ProjektGopher (1 commits)") --- Tags httphttpsclilaravelemailtrackingSNSwebhookses ### Code Quality TestsPHPUnit ### Embed Badge ![Health badge](/badges/antonbelous-laravel-ses-tracking/health.svg) ``` [![Health](https://phpackages.com/badges/antonbelous-laravel-ses-tracking/health.svg)](https://phpackages.com/packages/antonbelous-laravel-ses-tracking) ``` ### Alternatives [akhan619/laravel-ses-tracking A Laravel artisan based package to create the AWS (SES + SNS) infrastructure to receive email event notifications with Http/Https endpoint. 149.9k](/packages/akhan619-laravel-ses-tracking)[jbzoo/utils Collection of PHP functions, mini classes and snippets for everyday developer's routine life. 8321.5M36](/packages/jbzoo-utils)[renoki-co/laravel-aws-webhooks Easy webhook handler for Laravel to catch AWS SNS notifications for various services. 73248.5k](/packages/renoki-co-laravel-aws-webhooks)[akhan619/laravel-ses-event-manager A Laravel package to manage incoming SES email events with http/s webhooks. 148.8k](/packages/akhan619-laravel-ses-event-manager)[dragon-code/laravel-http-logger Logging incoming HTTP requests 319.8k3](/packages/dragon-code-laravel-http-logger)[ankurk91/laravel-ses-webhooks Handle AWS SES webhooks in Laravel php framework 2534.2k](/packages/ankurk91-laravel-ses-webhooks) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)