Setting up Amazon SES
How to point an installation on the Cloudflare target at your own Amazon SES account (ADR 0034, ADR 0037). The adapter itself is described in adapters/email-ses/README.md. Before real mail goes out, work through Turning on real mail.
Every value in angle brackets is a placeholder. Never commit real values: account IDs, domains, addresses, and keys stay in your AWS account, your Worker’s secrets, and your own deployment configuration.
| Placeholder | Meaning |
|---|---|
<account-id> |
Your 12-digit AWS account ID |
<region> |
An SES Region, for example eu-west-1; repeat the Regional steps for each Region you send through |
<prefix> |
A name prefix for your SES resources, for example cl |
<app-origin> |
The Worker’s public origin, for example https://app.example.com |
<worker-name> |
The name of your deployed Worker |
What you need
Section titled “What you need”- An AWS account with SES production access in each Region you send through. A sandbox account sends only to verified addresses and the mailbox simulator, which is enough for the smoke test.
- A public HTTPS origin for the Worker. With any provider but
fake, the Worker refuses anAPP_ORIGINthat is nothttps:, because RFC 8058 needs an HTTPS one-click unsubscribe link (ADR 0036). The EventBridge API destination also reaches only a public HTTPS endpoint with a publicly trusted certificate. - A choice between SES tenants and none:
- With tenants, each workspace has its own SES tenant, its own suppression list, and its sending domains associated with that tenant. This is what the managed service does, and cloud mode requires it.
- Without tenants, every workspace shares the account’s suppression list and sends without
TenantName. This is the simple setup for one operator who runs their own workspaces.
An installation that EventBridge cannot reach (behind NAT, for example) receives no SES events: messages whose outcome is unknown end as failed:outcome_unknown, bounces and complaints never reach suppression, and nothing is billed on the Send event.
1. IAM: send credentials
Section titled “1. IAM: send credentials”The Worker signs SendEmail requests with an IAM user’s access key: a Worker has no ambient AWS role to assume one with. Give that user only ses:SendEmail, on your configuration sets and the identities in your Regions:
{ "Version": "2012-10-17", "Statement": [ { "Sid": "SendOnly", "Effect": "Allow", "Action": "ses:SendEmail", "Resource": [ "arn:aws:ses:<region>:<account-id>:identity/*", "arn:aws:ses:<region>:<account-id>:configuration-set/<prefix>-<region>-transactional", "arn:aws:ses:<region>:<account-id>:configuration-set/<prefix>-<region>-marketing" ], "Condition": { "StringEquals": { "ses:ApiVersion": "2" } } } ]}- Repeat the three resources for each Region. One key signs for every Region the Worker sends through.
- With tenants, add
arn:aws:ses:<region>:<account-id>:tenant/*to the resources and require a tenant on every send with the condition"Null": { "ses:TenantName": "false" }, so no send can skip the tenant’s association check. - Manage tenants, identities, and suppression with other credentials (a role you assume, for example). They never belong to the Worker: the SES management API allows one request per second per account, and the send path must not depend on it.
- Create the access key with the AWS CLI and pipe it straight into
wrangler secret put SES_ACCESS_KEY_IDandSES_SECRET_ACCESS_KEY, so it never lands in a file in your checkout or in shell history. Rotate it with the user’s second key slot: create, deploy, confirm sends, deactivate the old key, then delete it.
2. Configuration sets (per Region)
Section titled “2. Configuration sets (per Region)”Create two configuration sets per Region, one per stream: <prefix>-<region>-transactional and <prefix>-<region>-marketing. The Worker names them with {region} in place of the Region (step 6).
Set their suppression. SES applies a configuration set’s suppression setting before the tenant’s and the account’s, so the set’s setting decides.
-
With tenants: every set uses tenant-level suppression, never the account-level list, so one workspace’s bounces never suppress an address for another (ADR 0034, clarified 2026-11-14):
Terminal window for set in <prefix>-<region>-transactional <prefix>-<region>-marketing; doaws sesv2 put-configuration-set-suppression-options --region <region> \--configuration-set-name "$set" \--suppression-scope TENANT \--suppressed-reasons BOUNCE COMPLAINTdoneNever pass an empty
--suppressed-reasonsinstead. That turns suppression off for the set, and because the set’s setting comes first, SES would then skip the tenants’ lists too. -
Without tenants: leave the sets’ suppression unset, so they use the account-level list. There are no tenant lists to use, and your workspaces share one operator’s account.
Then give each set an event destination on the Region’s default EventBridge bus, publishing Send, Reject, Bounce, Complaint, Delivery, DeliveryDelay, and Rendering Failure.
Check both sets:
aws sesv2 get-configuration-set --region <region> --configuration-set-name <set> --query SuppressionOptionsaws sesv2 get-configuration-set-event-destinations --region <region> --configuration-set-name <set>With tenants, expect SuppressionScope TENANT with reasons BOUNCE and COMPLAINT. Either way, expect one enabled EventBridge destination with the seven event types.
3. Tenants and tenant-level suppression (with tenants only)
Section titled “3. Tenants and tenant-level suppression (with tenants only)”For each workspace, in its Region, with the management credentials:
-
Create its SES tenant with tenant-level suppression: suppression attributes with scope
TENANTand reasonsBOUNCEandCOMPLAINT. -
Associate its sending identities (step 4) and both configuration sets with the tenant. SES refuses a send whose identity or configuration set is not associated with the tenant it names.
-
Record the tenant through the operator endpoint, with its Region if it is not
SES_REGION. Record the tenant before the workspace’s domains, because the first write of a workspace without a Region recordsSES_REGION(ADR 0037):Terminal window curl -X PUT <app-origin>/operator/workspaces/<workspace-id>/provider-tenant \-H "authorization: Bearer $OPERATOR_TOKEN" -H "content-type: application/json" \-d '{ "providerTenant": "<tenant-name>", "providerRegion": "<region>" }'
4. Sending domains
Section titled “4. Sending domains”For each domain a workspace sends from, in the workspace’s Region: create the SES email identity, publish its DKIM (and, if you use one, custom MAIL FROM) DNS records, and wait until SES reports it verified. With tenants, associate it with the workspace’s tenant. Then record it, which replicates it to every project store of the workspace (ADR 0035):
curl -X PUT <app-origin>/operator/workspaces/<workspace-id>/sending-domains/<domain> \ -H "authorization: Bearer $OPERATOR_TOKEN" -H "content-type: application/json" \ -d '{ "status": "verified" }'A 503 means a project store did not take the replica: run the resync (see Turning on real mail). A message whose from domain is not in its project’s replica is skipped as sender_not_verified, and skipped is final.
5. EventBridge: events back to the Worker (per Region)
Section titled “5. EventBridge: events back to the Worker (per Region)”SES publishes each sending event to the Region’s default bus. Forward them to the Worker:
-
Connection: API key authorization, with the header name
x-ses-events-secretand a random value (for exampleopenssl rand -hex 32). Store the same value in the Worker asSES_EVENTS_SECRET. Pass it through a file, not a command-line argument. Every Region’s connection carries the same value. -
API destination:
POST <app-origin>/provider-events/ses, with that connection. -
Rule on the default bus that forwards only the detail-types the Worker reads, from source
aws.ses:{"source": ["aws.ses"],"detail-type": ["Email Sent","Email Delivered","Email Delivery Delayed","Email Bounced","Email Complaint Received","Email Rejected","Email Rendering Failed","Sending Status Enabled","Sending Status Disabled"]}Forwarding everything from
aws.seswould send CloudTrail records and types AWS adds later to the Worker, which answers them 200 and ignores them. -
Target: the API destination, with a retry policy of 24 hours and 185 attempts, a role that lets the rule invoke the destination, and an SQS dead-letter queue (14 days’ retention, writable only by the rule).
-
Alarms: a CloudWatch alarm on the dead-letter queue’s
ApproximateNumberOfMessagesVisibleabove 0, and one on the rule’sRetryInvocationAttemptsthat lasts 15 minutes or more, both notifying a topic someone reads. The second shows a wrong secret or a failing Worker within minutes instead of after the 24 hours of retries.
What the Worker answers decides what EventBridge does:
| Answer | When | EventBridge |
|---|---|---|
| 200 | Applied, a duplicate, or a type the Worker ignores | Done |
| 401 | A wrong or missing secret, another source, or another account than SES_ACCOUNT_ID |
Retries for 24 hours, then dead-letters |
| 400 | An event of a type the Worker reads that it cannot read | Dead-letters at once |
| 503 | EMAIL_PROVIDER is not ses (before the rollout, or after a rollback) |
Retries for 24 hours, then dead-letters |
| 500 | The Worker’s configuration is refused, or a store failed | Retries for 24 hours, then dead-letters |
So the rule can be created before EMAIL_PROVIDER=ses is turned on: events retry for a day and then wait in the dead-letter queue for replay. Never switch a self-hosted Worker that has real messages queued back to fake: outside cloud mode, the fake provider accepts them and reports them delivered, so they are marked sent and billed while nobody receives them. In cloud mode it refuses every send instead (below). To stop sending, see Emergency stop.
Replay from the dead-letter queue
Section titled “Replay from the dead-letter queue”Each message in the queue is an original EventBridge event; its attributes say why delivery failed.
- Fix the cause: the Worker’s URL, the secret, or the Worker itself.
- Post each message body to
<app-origin>/provider-events/seswith the headerx-ses-events-secret. - Delete each message after a 2xx. Leave a 400 in the queue and investigate it.
Replays are safe: the Worker deduplicates by the EventBridge event id, and message states never move backwards.
6. Configure the Worker
Section titled “6. Configure the Worker”Plain variables (in your deployment configuration):
| Variable | Value |
|---|---|
EMAIL_PROVIDER |
ses; fake, the default, sends nothing real |
APP_ORIGIN |
<app-origin>, which must be https: |
SES_REGION |
The default Region, <region> |
SES_REGIONS |
Optional: the comma-separated Regions a workspace may be assigned; leave it unset for one Region |
SES_CONFIGURATION_SET_TRANSACTIONAL |
<prefix>-{region}-transactional |
SES_CONFIGURATION_SET_MARKETING |
<prefix>-{region}-marketing |
SES_ACCOUNT_ID |
Optional: <account-id>, so events of any other account are refused |
Secrets (wrangler secret put <name> --name <worker-name>): SES_ACCESS_KEY_ID, SES_SECRET_ACCESS_KEY, and SES_EVENTS_SECRET.
The Worker checks these on every request. A missing or malformed value fails every request with a 500, logs refusing to serve: and the variable’s name (never its value), and returns every delivery job to the queue unsent. A job may be dropped once the queue’s retries run out, but its message stays queued and the store enqueues it again when its deadline passes (ADR 0011), so nothing is sent until the setting is fixed, and nothing is lost. The operator endpoints accept exactly the Regions the adapter sends through, because both come from the same parsed SES_REGION and SES_REGIONS.
In cloud mode (CUSTOMER_LITE_CLOUD set), a message of a workspace whose replica has no provider tenant is never sent: it goes back to the queue as queued:provider_unavailable with providerReason provider_tenant_missing, raises an operator alert, and fails as failed:provider_unavailable if no tenant is recorded within 24 hours of its first attempt.
Also in cloud mode, an unset EMAIL_PROVIDER or fake sends nothing: every send is recorded the same way with providerReason fake_in_cloud_mode and alerted, and every event posted to /provider-events/fake is refused with 401. The API, one-click unsubscribe, and approval links keep working, so a deploy that lost the variable loses no mail if it is fixed within 24 hours.