Setting up AWS SNS/SES bounce notifications for Mailtrain

Mailtrain is a NodeJS based self hosted Newsletter app built upon Nodemailer. I’ve been having a play around with it and Amazon SES (Simple Email Service) whilst toying with the idea of setting up a weekly newsletter. The issue with not using a local MTA (such as Postfix) is that bounce receipts get lost.

Mailtrain already has webhooks available that Amazon can POST to, but documentation around the setup for it is sadly lacking. So after some trial and error I’ve got it all working with the following.

Create a SNS Topic

First things first, you need to create a SNS topic that will send POSTs to Mailtrain. Go to your Amazon console and go to SNS. Then create a new topic:

It doesn’t have to be called mailtrain-bounces but it should be named something you can easily identify/remember later.

Create a SNS Subscription

This is where half the magic happens. You need to tell SNS that it should send notifications to this topic on to Mailtrain. Select your topic you just created and click Create Subscription. Whether you select HTTP or HTTPS as the Protocol is up to you, but if you aren’t using HTTPS you really should be!

The endpoint is just http[s]://<your_mailtrain_domain>/webhooks/aws.

Initially the endpoint status will likely be Pending but if you give it a refresh you’ll see a Subscription ID appear in the first box in the table once SNS confirms the endpoint works.

When creating the Subscription ensure that Raw message delivery is Disabled.

Setup SES Notifications

Finally, we need to edit your SES configuration so it sends bounce notifications for this domain/email to Mailtrain. This step will be slightly different depending on whether you’ve setup the whole domain or just a single email in SES. Either way the changes are mostly the same, just a different left hand menu.

If you have a domain setup in SES you’ll need to edit it via the Domains menu, if its just a single email address you’ll need to edit it via the Email Addresses menu.

Note: I would recommend setting up the specific email/s you’re sending your newsletters from. This way you can just send bounce notifications for these specific emails to Mailtrain as opposed to all bounces that go through SES for that domain.

Once you’ve selected either your domain or email address you’re using in Mailtrain click on the Notifications drop down and edit the configuration. Enter the SNS topic into Bounces and Complaints and boom! You’re all done.

You can try and send a test campaign to an email address that doesn’t work (like this_email_wont_work@geeeeeeeeeeeemail.com) and you should see POST requests from Amazon SNS to your Mailtrain instance reporting the bounce.