Provision Amazon SES

Gateman supports customers at different stages of their Amazon SES setup. It can assist with a new SES sending integration, work with supported existing SES configuration, or configure Gateman's SES email event tracking for an existing sending setup.

This is separate from Send email, which documents the sending request contract. Standard email.send sending does not require managed provisioning, and an application does not have to rebuild an SES account that it already manages.

Managed SES provisioning and managed SES event tracking are Premium console features. The console is the provisioning interface; this is not a general AWS or IAM administration service.

Choose your SES setup

From the application's SES section, Gateman presents these choices:

Full SES provisioning — set up or verify the AWS access, SES domain identity, DNS, runtime sending identity, email tracking, and production readiness for the application.
Email tracking only — connect Gateman's SES event integration to an existing SES sending setup without provisioning a new sending domain or runtime sending identity.

If SES sending is already configured and you do not need Gateman-managed event tracking, keep using your existing provider configuration with email.send.

Full SES provisioning

Full provisioning is for an application that needs Gateman to establish the supported SES sending and tracking components. It can verify and reuse supported existing resources, but it does not silently adopt resources whose ownership or configuration cannot be established.

Before you begin

Have the following ready:

Access to the AWS account that will own the SES resources.
An IAM user named exactly Gateman-Setup, without console access.
A temporary access key for that user.
The one-time Gateman-Bootstrap inline policy shown in the console. It permits Gateman to verify the setup identity and create or attach only the supported Gateman SES setup policy.
A supported SES region and the sending domain you want to verify.
Access to the Cloudflare zone containing that domain, if Cloudflare manages its DNS.
A Cloudflare custom API token named Gateman-SES-DNS, restricted to the relevant zone with only Zone Read and DNS Write permissions. A Global API Key is not supported.

The domain must be yours to configure. You may also need to approve the SES verification email and review the DNS records that Gateman publishes.

Workflow

Select Full SES provisioning, then select Start SES setup. Enter the AWS region, sending domain, temporary IAM access key ID, temporary IAM secret access key, and Cloudflare API token.

Gateman proceeds in dependency order:

It verifies the AWS setup identity and the selected Cloudflare zone.
It installs or verifies Gateman-SES-Setup, creates the required IAM permission boundaries, and creates or verifies the persistent Gateman-SES-Control identity.
It creates or verifies the SES domain identity in the selected region.
It publishes the SES Easy DKIM CNAME records and DMARC TXT record to the verified Cloudflare zone. SES verification is asynchronous; use **Check SES verification** after the records have propagated.
It creates or verifies the SES configuration set and gateman-events destination, creates or verifies the SNS event topic, applies the required SNS publish policy, and creates or continues the HTTPS subscription to Gateman's SES webhook.
It creates the application's SES runtime IAM user and access key, applies the least-privileged runtime policy, verifies the identity with AWS STS, and stores the runtime credentials in encrypted application storage.

The runtime policy permits SES SendEmail and SendRawEmail, plus the SES health checks Gateman needs. It restricts the sending address to the configured domain, the selected region, and Gateman's configured egress addresses. The runtime user has the Gateman-SES-Runtime-Boundary permissions boundary and does not receive IAM administration authority.

After the persistent control identity is verified, Gateman revokes the exact temporary setup access key and removes its encrypted setup copy. A DNS, provider, SES-verification, or SNS-confirmation wait is persisted. Refresh or resume the workflow to continue. Completed resources are preserved; Gateman does not broadly roll back or delete partially provisioned AWS resources.

Full setup may verify or reuse supported existing resources. An existing customer-managed SES configuration set can be selected explicitly from the Email tracking page. Gateman validates and reuses it, adds only the event tracking integration it needs, and does not claim ownership of that set.

Configure email tracking only

Choose Email tracking only when the customer already has SES sending configured and wants Gateman to receive SES delivery events and maintain Gateman email status and suppression behavior. The existing sending identity, sender configuration, and production-access state remain the customer's responsibility.

Tracking-only prerequisites

Tracking-only requires:

Premium entitlement;
the existing SES sending setup and the AWS region in which it operates;
an IAM user named exactly Gateman-Setup, without console access;
the Gateman-Bootstrap inline policy shown in the console; and
a temporary access key for that setup user.

Tracking-only does not require a Cloudflare token, a sending domain for Gateman to verify, a new SES domain identity, a new SES runtime IAM user, or a new production-access request. It also does not run the full provisioning sandbox readiness sequence.

Tracking-only workflow

Open the application's SES section and select Email tracking only. Enter a supported AWS SES region, the temporary Access key ID, and Secret access key, then select Verify AWS access and start tracking.

Gateman verifies the account, establishes or reuses the persistent Gateman-SES-Control identity, and configures the tracking path:

It verifies or creates the SES configuration set used for tracking. If the customer selects Use my own SES configuration set, Gateman validates the supplied existing set and records it as customer-managed. Otherwise it uses its deterministic Gateman configuration-set name and creates it when it is absent.
It verifies or creates the deterministic SNS event topic and merges the required Gateman publish-policy statement.
It verifies an existing HTTPS subscription for this application's Gateman SES webhook or creates one. A new subscription may remain pending until AWS confirms it; the console exposes the waiting state and a status refresh.
It verifies or creates the gateman-events SES event destination for the selected configuration set, covering send, delivery, bounce, complaint, and reject events.

An exact existing SNS subscription or a matching gateman-events destination can be reused. A conflicting configuration, unexpected deterministic topic, or resource whose ownership cannot be established stops the relevant step rather than being silently overwritten or adopted. Customer-managed configuration sets remain customer-owned.

After SNS confirmation and event-destination setup, select Activate email tracking when the console presents that action. Verify the connection from the Email tracking page by confirming that tracking is active. The temporary setup credential is revoked after the persistent control identity and tracking resources are established; an incomplete revocation remains a recoverable state.

Tracking-only does not create or replace the customer's SES sending identity or runtime sending credentials. The customer must ensure that its SES sends use the configuration set connected to Gateman's event destination.

Sending readiness

Sending readiness depends on the AWS SES account state and the selected setup mode.

Already in production

Gateman checks SES account state for the selected AWS account and region. If AWS reports production access is already enabled, the customer does not need to repeat sandbox recipient verification, simulator testing, or a production- access request merely because the account is being used with Gateman.

For tracking-only setup, sending readiness and production access are outside the tracking workflow. The existing SES sending configuration remains the customer's responsibility.

Still in the SES sandbox

For full provisioning when the account remains in the sandbox, Sending readiness guides these checks:

Enter a recipient address that you control, select **Send verification email, confirm the SES email, and select Check recipient verification** until Gateman records the recipient as verified.
Select Send sandbox test email. Gateman sends a normal test message from the verified domain to that verified recipient through the configured SES runtime and configuration set, then waits for the delivery event.
Select Run SES sending tests. Gateman sends the SES simulator cases for success, bounce, and complaint and checks the corresponding SES/SNS events.

Gateman marks these full-provisioning checks complete only after the recipient is verified, the normal test is delivered, and the success, bounce, and complaint simulator outcomes are observed. These checks are not universal requirements for existing production accounts or tracking-only setup.

If SES reports that sending is disabled or otherwise restricted, the console shows the account's sending state and the relevant readiness state. AWS account and provider restrictions remain the customer's responsibility; this page does not promise a Gateman recovery control that the console does not provide.

Requesting production access (if required)

This step applies only when the selected AWS account and SES region remain in the sandbox and the customer wants production sending. An account that already has production access does not need to submit the request again.

After the full-provisioning domain, DNS, runtime, tracking, recipient, test-send, and simulator checks are complete, Gateman can submit the request from the Sending readiness page.

The form collects:

the primary email type: Transactional or Marketing;
the business website URL;
up to four additional contact email addresses; and
the AWS contact language: English or Japanese.

Gateman submits these values to SES with PutAccountDetails using the persistent Gateman-SES-Control identity. It reads the AWS response to show pending, granted, denied, or failed status and retains a case reference when AWS provides one. It does not use the deprecated free-form UseCaseDescription field.

AWS makes the final decision. Gateman cannot approve the account or guarantee a review time. AWS may contact the customer or request more information directly. The console provides a copyable Technical setup summary for AWS Support containing the configured domain, region, DKIM and DMARC state, control and runtime identities, configuration set, SNS topic/subscription, and event types. The customer remains responsible for replying to AWS and meeting AWS sending policies.

After setup

The application uses Gateman's email.send capability for normal production email requests. See Send email for the request and response contract.

When tracking is active, Gateman receives the configured SES/SNS delivery events and maintains its email status and suppression behavior. It does not forward provider events to the customer application. Open tracking, click tracking, unsubscribe handling, and marketing-preference management remain application responsibilities.

SES configuration sets, SNS resources, event destinations, IAM identities, and other provider resources are created in the customer's AWS account. The customer owns and administers that account, including AWS billing, DNS, provider policy, production approval, and cleanup. Removing Gateman's encrypted copy is not the same as deleting every AWS resource.