AWS SES & SNS Setup for Email Delivery Tracking (Console Guide)

This guide walks you through configuring your AWS account only — no code. Once done, AWS will send delivery, bounce, and complaint events to your app at POST https://YOUR_APP_HOST/webhooks/ses.

---

CRITICAL: Use the Same AWS Account as Your SMTP

You must do all of this setup in the AWS account that owns the SMTP credentials your app uses to send email.

• Your app sends email via MAIL_USERNAME and MAIL_PASSWORD (from config/application.yml or env).
• Those credentials belong to a specific AWS account (yours, your client’s, or whoever provided them).
• The configuration set, SNS topic, and subscription must all be created in that same account.

If you use a different account (e.g. your own while the client’s account sends the mail), SES will reject with: "Configuration set does not exist" — because that config set doesn’t exist in the account that’s actually sending.

Before continuing: Log into the AWS account that owns the SMTP credentials. Confirm by checking the account ID in the top-right of the console.

---

Before You Start

• SES is already sending mail from your app (you’re using SES to send the emails you want to track).
• You know your public app URL (e.g. https://app.peptalk.com). The webhook will be:
  https://YOUR_APP_HOST/webhooks/ses
• Your app is reachable over HTTPS from the internet (so AWS can POST to that URL).

---

Region: Must Match Your SMTP Endpoint

SES configuration sets and SNS topics are region-specific. Use the same region as your SMTP endpoint:

• If you send via email-smtp.eu-west-1.amazonaws.com → use eu-west-1 (Ireland).
• If you send via email-smtp.ap-southeast-1.amazonaws.com → use ap-southeast-1 (Singapore).

Switch region in the AWS Console (top-right dropdown) before creating the configuration set and SNS topic.

---

Overview (What You’ll Do)

1. SNS: Create one or more “topics” that will receive event notifications from SES.
2. SES: Turn on “event publishing” for Delivery (and optionally Bounce, Complaint) and send those events to the SNS topic(s).
3. SNS: Add an “HTTPS subscription” so that when the topic gets an event, SNS POSTs it to your app’s /webhooks/ses URL.
4. Confirm: Let SNS confirm the subscription (your app can do this automatically when it receives the confirmation request).

---

Step 1: Create SNS Topics

SNS topics are the “channels” that SES will publish to. You can use one topic for all event types or separate topics.

1. In AWS Console, open Amazon SNS (search “SNS” in the top search bar).
2. In the left sidebar, click Topics.
3. Click Create topic.
4. Type: Standard.
5. Name: e.g. ses-email-events (or create three: ses-delivery, ses-bounce, ses-complaint).
6. Leave other settings as default. Click Create topic.

Note the Topic ARN (e.g. arn:aws:sns:us-east-1:123456789012:ses-email-events). You’ll need it in Step 2.

---

Step 2: Enable SES Event Publishing (Delivery, Bounce, Complaint)

This tells SES to send events to your SNS topic(s).

1. In AWS Console, open Amazon SES (search “SES”) in the same region as your SMTP endpoint.
2. In the left sidebar, go to Configuration → Configuration sets.
3. Click Create set.
4. Name: e.g. ses-mail-events (remember this — you’ll set SES_CONFIGURATION_SET in your app).
5. Click Create set, then open the new set.
6. Click Add destination (or Add event destination).
7. Destination type: Amazon SNS.
8. SNS topic: Choose the SNS topic you created (e.g. ses-email-events).
9. Event types: Enable Deliveries (and optionally Hard bounces, Complaints).
10. If you see Include original email headers, turn it ON — required for matching by X-Peptalk-Delivery-ID.
11. Save.

(Some regions show *Configuration** → Notifications instead; the flow is similar: enable each event type and choose the SNS topic.)*

---

Step 3: Subscribe Your App URL to the SNS Topic(s)

So far, SES will publish events to SNS. Now you need SNS to forward those events to your app.

1. Go back to SNS → Topics.
2. Click the topic you used in Step 2 (e.g. ses-email-events).
3. Scroll to Subscriptions.
4. Click Create subscription.
5. Topic ARN: Should already be filled.
6. Protocol: HTTPS.
7. Endpoint: Your webhook URL, e.g.
   https://app.peptalk.com/webhooks/ses
   (use your real host; no trailing slash).
8. Click Create subscription.

The subscription will show status Pending confirmation until your endpoint confirms it.

---

Step 4: Confirm the Subscription

When you created the subscription, SNS sent a POST request to your URL with a SubscriptionConfirmation message. Your app (e.g. SesController) is built to:

• Receive that POST
• Read the SubscribeURL from the body
• Call that URL to confirm

So in most cases you don’t need to do anything: once the app is deployed and the URL is reachable, refresh the SNS Subscriptions list and the status should change to Confirmed.

If it stays Pending confirmation:

• Ensure the app is live at https://YOUR_APP_HOST/webhooks/ses.
• Ensure HTTPS is valid (no certificate errors).
• Check that nothing (firewall, load balancer, app) is blocking or returning errors for POSTs from AWS.
• In SNS, you can open the subscription and use Request confirmation to send the confirmation again.

---

Step 5: Verify Permissions (If Events Don’t Arrive)

SES must be allowed to publish to the SNS topic. Usually AWS sets this when you configure the notification in Step 2.

If delivery events never show up:

1. In SNS → Topics, open your topic.
2. Go to the Access policy (or “Edit” the policy).
3. Ensure there is a statement that allows SES (or ses.amazonaws.com) to Publish to this topic. If you used the console to link SES in Step 2, this is usually already there.

---

Checklist Summary

Step	Where	What to do
0	AWS Console	Log into the AWS account that owns the SMTP credentials (MAILUSERNAME/MAILPASSWORD)
1	SNS → Topics	Create topic(s), e.g. ses-email-events
2	SES → Configuration → Notifications	For Delivery (and Bounce/Complaint): enable, select SNS topic, enable “Include original email headers”
3	SNS → Topic → Subscriptions	Create subscription: Protocol HTTPS, Endpoint https://YOUR_APP_HOST/webhooks/ses
4	(Automatic)	App confirms subscription when SNS POSTs; check subscription status = Confirmed
5	(If needed)	SNS topic access policy allows SES to Publish

---

After Setup

• When an email is delivered (or bounces/complaints), SES publishes to SNS and SNS POSTs to https://YOUR_APP_HOST/webhooks/ses.
• Your app parses the payload and creates the right CommsEvent (e.g. event_type: 'delivered') using the X-Peptalk-Delivery-ID header from the original email.

For testing and code details (open pixel, click tracking, env vars), see EMAILTRACKINGSETUP.md.

---

App Wiring: Configuration Set Name

After AWS is configured, your app must send emails with the X-SES-CONFIGURATION-SET header so SES uses your event destination. Set SES_CONFIGURATION_SET in your environment (e.g. in config/application.yml):

SES_CONFIGURATION_SET: ses-mail-events

The value must match the configuration set name you created in AWS.