Amazon SES

This page is for a store sending through Amazon SES that wants delivered, bounced and complained figures on its campaign screens. Read Delivery reports and providers first for what a provider webhook is and what the store does with each event.

SES has no webhooks. It publishes events to an SNS topic, and getting from "a message bounced" to "a POST arrives at this store" takes six calls. The Set up in Amazon SES button makes all six.

Before you begin

• An AWS account with SES out of the sandbox, and a verified identity (a domain or an address).
• An access key id and secret access key, and the AWS region you send from.
• The grav-plugin-email-amazon plugin at 1.1.2 or later, with the Grav Email plugin at 5.2.0 or later on PHP 8.1 or later.
• The Email plugin's Mail Engine set to Amazon SES.

What the IAM policy must allow

The same access key sends the mail and sets the reports up. Grant these actions on the key's own user or role under IAM, not in SES.

When a call is refused, the button prints Amazon's own sentence and names the step, so you know which action to add.

There is no verification key to paste. Amazon signs every message with a certificate whose address travels in the message.

Configure the transport

The transport is a Grav plugin, so its own settings live in the Grav admin's plugin list. The webhook that reports deliveries back is set up from the Providers card in the KahunaCart admin, in the next section.

1. 1

   In the Grav admin's plugin list, open Email Amazon and set Transport.

   Read the warning below the table first. The short version is that API leaves custom headers behind, so it is the wrong choice for newsletters.

2. 2

   Fill in Access Key, Secret Key and Region.

   The region is the one your senders are verified in. If you are not sure, the SES console shows nothing at all in the wrong one.

3. 3

   Fill in Configuration set and SNS topic under the delivery-reports fields.

   The defaults, grav-email and grav-email-events, are fine unless something else on the account already uses those names. Pick names nothing else uses: a configuration set is account-wide and shared with anything else sending through SES.

4. 4

   Leave Sending identity empty unless you know you want it.

   Filling it in makes this configuration set the default for that identity, so every message from that address or domain publishes here, including messages sent by something other than this store. That is the one setting on this page that reaches outside the plugin. Left empty, the step is skipped and said so plainly.

5. 5

   Open Email in the same plugin list and set Mail Engine to Amazon SES.

Set the reports up in one click

1. 1

   Go to KahunaCart → Add-ons → Newsletters → Settings → Providers and click Generate a secret on the Amazon SES card.

2. 2

   Click Set up in Amazon SES.

   Six calls, listed below. Each failure names which step it was, because an AccessDenied on the topic and one on the event destination need different IAM actions added and read identically otherwise.

The button runs six steps in order.

1. Create the SNS topic, or reuse an existing one with that name. The default name is grav-email-events.
2. Read the topic's policy, then write it back with one statement added, letting ses.amazonaws.com publish to that topic, conditioned on your own account id. Everything else on the policy stays. The statement is replaced rather than appended, so pressing twice changes nothing.
3. Subscribe the store's webhook address over HTTPS.
4. Create the configuration set if it does not exist. The default name is grav-email.
5. Create or update the event destination named grav-email-sns, listening for DELIVERY, BOUNCE, COMPLAINT, OPEN, CLICK and REJECT.
6. Make the configuration set the identity's default, only when Sending identity is filled in.

Leave Sending identity empty and step 6 is skipped, with a sentence saying what is still outstanding.

The confirmation handshake

The first thing SNS sends to a new subscription is a SubscriptionConfirmation asking the endpoint to fetch a URL. The store makes that request itself, over HTTPS only, only to a host matching sns.<region>.amazonaws.com, and never to a URL carrying credentials. You do not have to click anything.

Nothing is published to a subscription until it is confirmed.

An UnsubscribeConfirmation is noted and never confirmed. Confirming it would resubscribe the store to a topic somebody had just removed it from.

Do it by hand instead

1. 1

   In the SES console, go to Configuration sets and create one, or open the one you send with.

2. 2

   On its Event destinations tab, add a destination of type Amazon SNS, pick or create a topic, and tick Delivery, Bounce, Complaint and Reject.

3. 3

   In the SNS console, open that topic and create a subscription with protocol HTTPS and the store's webhook address as the endpoint.

   Amazon posts a confirmation straight away and the store answers it for you. Check the subscription afterwards: one still reading PendingConfirmation looks registered in every list and delivers nothing.

4. 4

   Either set the configuration set as the default on the verified domain under Identities, or send with an X-SES-CONFIGURATION-SET header naming it.

   Do the first one only if you are happy that everything sending as that identity publishes here.

There is no separate header list to fill in. SES returns the message's headers on an event-publishing notification without being asked.

What each event means

A complaint whose feedback type is not-spam is skipped.

A bounce produces one event per bounced recipient.

A Reject is always the message and never the address

SES never refuses a send because of the recipient. An address it will not deliver to bounces, and the account-level suppression list produces a permanent Bounce with the subtype Suppressed, not a Reject. AWS's own documented reason for a Reject is Bad content, meaning SES detected a virus.

So a Reject marks the send bounced and touches nothing about the person, whatever its reason string says.

Provider quirks

Both spellings of the type field are read. Event publishing calls it eventType; an identity feedback notification calls it notificationType.

The send id survives header truncation in the message tags. SES truncates the header list on a message with around 10 KB of headers and sets headersTruncated. The store reads the send id from the header list first and from mail.tags second.

commonHeaders.messageId is not the store's Message-ID. On an event it is the id SES assigned; on a notification it is the original. The parser reads neither and joins on the header list instead.

An identity feedback notification carries no headers unless you asked for them. For a notification sent straight from a verified identity rather than through a configuration set, tick Include original email headers on the identity's page, once per feedback type. Event publishing carries them without being asked.

Amazon signs, and the certificate is fetched and cached. The store checks the signature against a certificate fetched from the address in the message, only over HTTPS and only from a host matching sns.<region>.amazonaws.com, and keeps it under user/data/email-amazon/ for thirty days. Both of Amazon's signature versions are accepted, because an SNS topic defaults to version 1.

A message with an attachment keeps its headers even on the api transport, because the Symfony bridge falls back to raw MIME for those. That is not a reason to use api for campaigns.

DNS for the Health tab

SES aligns a custom return path with an MX record on a subdomain of your own domain, so there is no return-path zone to check a name against.

With the ses:GetEmailIdentity permission on the key, the Health tab reads the real DKIM tokens and the MAIL FROM domain off your account. Without it, put the token into deliverability.dkim_selector on KahunaCart → Add-ons → Newsletters → Settings → Health.

Checking it actually works

Send a one-recipient campaign to an address you can read, open it, press a link, then check the Amazon SES card. On SES this check earns its keep twice over, because an unconfirmed subscription is invisible everywhere else.

Troubleshooting

Related

• Delivery reports and providers
• Health
• Campaigns
• Settings reference
• Emails