Amazon SES and SMTP email provider setup runbook

Amazon SES and SMTP email provider setup runbook tells implementation teams exactly which email-provider credentials, sender identities, callback settings, SquareOS fields, and go-live evidence are required before invoice, payment-link, reminder, campaign, or automation email is trusted in production.

What this page is for

Who should use it

Owner, implementation, communications admin, platform admin, support

Where to find it

AWS Console / Amazon SES, SMTP provider admin panel, SquareOS Admin / Email Setting

Before you start

Amazon SES and SMTP email provider setup runbook: complete this runbook before a gym treats email as production-ready in SquareOS.
Amazon SES setup starts in AWS Console / Amazon SES / selected sending region and records region, verified identity domain or sender email, DKIM/SPF/DMARC or MAIL FROM status, SES sandbox or production state, access key id, secret access key reference, optional session token, and configuration set name.
Amazon SES notification setup records SNS topic ARN, SES event publishing or notification settings for delivery, bounce, complaint, reject, rendering failure, delivery delay, subscription confirmation state, SquareOS callback URL POST /engagement/email/ses/webhook, webhook verify token, and requireSnsSignature rule.
SMTP setup records host, port, TLS/secure requirement, username, password or secret reference, from address, reply-to address, provider message id availability, certified adapter callback URL POST /engagement/email/smtp/webhook, and webhook verify token.
SquareOS Email fields map provider values to Channel Account channel EMAIL, provider SES or SMTP, accountName, externalAccountId as SES identity/configuration set or SMTP sender identity, configJson region/configurationSetName/snsTopicArn/requireSnsSignature/webhookVerifyToken or host/port/secure/webhookVerifyToken, credentialsJson accessKeyId/secretAccessKey/sessionToken or username/password, fakeModeEnabled, Sender Account senderValue, and template channel EMAIL.
Email go-live proof requires fake mode off, one opted-in internal recipient, SES SendEmail MessageId or SMTP queued id, DeliveryAttempt providerMessageId, Message providerMessageId, SES SNS Delivery/Bounce/Complaint callback or certified SMTP adapter callback, CampaignDeliveryLog update when campaign-originated, and no unresolved dead-letter.
SES webhook verification must reject mismatched webhook token, mismatched SNS topic ARN, or invalid SNS signature when requireSnsSignature is true, and must not update DeliveryAttempt, Message, or CampaignDeliveryLog on failed verification.
SMTP adapter callbacks must match providerMessageId or message id, event/status, timestamp, optional error text, and configured token before delivery rows change.
Email secret handling forbids exposing SES secret access key, SMTP password, webhook token, raw SNS payload, raw SMTP adapter callback, DNS credentials, or provider portal screenshots containing credentials in launch notes, mobile screens, support tickets, analytics, or crash logs.
If SES or SMTP portal labels differ from the runbook, the extraction row must record current portal path attempted, DNS/admin owner, support ticket id, copied value, SquareOS field, masked secret handling, and verification action.

Daily workflow

Confirm whether the gym uses Amazon SES or an SMTP relay. Do not configure both as active production senders unless support has documented routing and both providers will be certified separately.
For Amazon SES, sign in to AWS Console, choose the sending region, open Amazon SES, and record the region exactly as SquareOS will use it, such as ap-south-1. SES identities and sandbox status are region-specific, so do not copy a verified identity from one region into another region without verification.
Open Amazon SES / Verified identities. Record the verified domain or sender email, DKIM state, SPF/DMARC or custom MAIL FROM status where used, and whether verification is pending or failed. If DNS records are missing, assign the DNS/admin owner and keep email disabled until the provider confirms verification.
Open Amazon SES sending/account status. Record whether the account is in sandbox or production. Sandbox accounts can send only to verified recipients, so payment-link or invoice email must stay disabled for real customers until production access is approved.
Open or create the SES configuration set used for SquareOS sends. Record the configuration set name only if it will be attached to SendEmail. If no configuration set is used, leave the field empty instead of inventing a value.
Create or select the IAM credential SquareOS will use for SES SendEmail. Record access key id and optional session token where applicable, but store the secret access key only in the SquareOS credential field or approved secret manager reference. Do not put the secret access key in notes or screenshots.
Configure SES notifications through event publishing or notification settings. Create or select the SNS topic, subscribe the SquareOS callback URL POST /engagement/email/ses/webhook, confirm the subscription, and enable the events used for certification: delivery, bounce, complaint, reject, rendering failure, and delivery delay where supported.
Record the SNS topic ARN, subscription confirmation state, webhook verify token, and whether requireSnsSignature is enabled. If requireSnsSignature is true, SquareOS must verify SNS signing certificate URL shape, signature, and configured topic ARN before changing delivery rows.
In SquareOS Admin / Email Setting, create a Channel Account with channel EMAIL, provider SES, accountName such as SES Live - Main Gym, externalAccountId as the verified identity or configuration-set reference, configJson region/configurationSetName/snsTopicArn/requireSnsSignature/webhookVerifyToken, credentialsJson accessKeyId/secretAccessKey/sessionToken, and fakeModeEnabled only while testing workflow shape.
Create a Sender Account with senderValue as the verified from address customers should see. Create or map EMAIL templates for invoice, payment link, renewal, trial, freeze/cancellation, appointment reminders, and campaigns only after the sender identity is verified.
For SMTP, open the mail provider or relay admin panel. Record relay host, port, whether implicit TLS/secure mode is required, username, password or secret reference, from address, reply-to address, and whether the provider exposes a queued/provider message id that SquareOS can match later.
For SMTP callbacks, configure the certified adapter or mail gateway callback to POST /engagement/email/smtp/webhook. The adapter must send providerMessageId or message id, event/status, timestamp, optional error text, and the configured token through ?token= or x-webhook-token.
In SquareOS Admin / Email Setting, create a Channel Account with channel EMAIL, provider SMTP, accountName, externalAccountId as SMTP sender identity, configJson host/port/secure/webhookVerifyToken, credentialsJson username/password, fakeModeEnabled only while testing, then create a Sender Account for the from address.
Send one live internal email with fake mode off. For SES, capture SendEmail MessageId and the matching SES SNS Delivery/Bounce/Complaint callback. For SMTP, capture queued id/provider message id and the matching certified adapter callback.
Confirm SquareOS updated DeliveryAttempt providerMessageId, Message providerMessageId/status, CampaignDeliveryLog when campaign-originated, outbox/dead-letter state, and provider readiness without unresolved failure. Attach the certification evidence row id to the extraction row.
Record official source references used for the extraction row: Amazon SES verified identities, Amazon SES event publishing/notifications, Amazon SES configuration sets, Amazon SNS message signature validation, and the SMTP relay provider documentation or RFC-backed TLS/port policy used by the provider.

Watch out

Do not treat a successful queue row as delivered email. Production proof requires provider message id plus SES SNS callback or certified SMTP adapter callback.
Do not use personal mailbox credentials for official invoices, payment links, or campaigns unless the owner, mail provider policy, SPF/DKIM/DMARC setup, and support runbook explicitly approve it.
Do not disable SNS signature or topic ARN verification in production unless support records an accepted limitation and the callback endpoint is otherwise protected by a vetted adapter/token path.
Do not expose secret access keys, SMTP passwords, webhook tokens, DNS admin screenshots, raw SNS envelopes, or SMTP adapter payloads in launch evidence, mobile screens, support tickets, analytics events, or crash logs.
Do not switch an SES account out of sandbox in the docs before AWS has approved production sending. Staff-facing email actions should stay disabled or clearly limited until real customer recipients are allowed.
Do not reuse one SES/IAM credential or SMTP relay across tenants unless brand ownership, sender identity, domain verification, suppression handling, billing, and tenant mapping are explicitly approved.

Use the left menu to open related pages in Start Here.
Use Ask Docs for questions that are already covered in this public documentation.