Skip to content

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
  • 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 an APP_ORIGIN that is not https:, 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.

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_ID and SES_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.

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; do
    aws sesv2 put-configuration-set-suppression-options --region <region> \
    --configuration-set-name "$set" \
    --suppression-scope TENANT \
    --suppressed-reasons BOUNCE COMPLAINT
    done

    Never pass an empty --suppressed-reasons instead. 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:

Terminal window
aws sesv2 get-configuration-set --region <region> --configuration-set-name <set> --query SuppressionOptions
aws 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:

  1. Create its SES tenant with tenant-level suppression: suppression attributes with scope TENANT and reasons BOUNCE and COMPLAINT.

  2. 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.

  3. 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 records SES_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>" }'

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):

Terminal window
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:

  1. Connection: API key authorization, with the header name x-ses-events-secret and a random value (for example openssl rand -hex 32). Store the same value in the Worker as SES_EVENTS_SECRET. Pass it through a file, not a command-line argument. Every Region’s connection carries the same value.

  2. API destination: POST <app-origin>/provider-events/ses, with that connection.

  3. 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.ses would send CloudTrail records and types AWS adds later to the Worker, which answers them 200 and ignores them.

  4. 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).

  5. Alarms: a CloudWatch alarm on the dead-letter queue’s ApproximateNumberOfMessagesVisible above 0, and one on the rule’s RetryInvocationAttempts that 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.

Each message in the queue is an original EventBridge event; its attributes say why delivery failed.

  1. Fix the cause: the Worker’s URL, the secret, or the Worker itself.
  2. Post each message body to <app-origin>/provider-events/ses with the header x-ses-events-secret.
  3. 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.

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.