Why migrate
AWS will sign a Business Associate Agreement (BAA) that covers SES as a service, but the BAA does not protect Protected Health Information (PHI) in the body of the mail once it leaves AWS. SES TLS enforcement defaults to opportunistic (TlsPolicy: OPTIONAL), so messages silently fall back to plaintext when the recipient server doesn’t advertise STARTTLS; the customer carries the encryption-in-transit obligation.
Paubox closes that gap with TLS on by default, an automatic Secure Portal fallback when the recipient cannot accept encrypted mail, and a BAA signed with every customer. The send-side API is REST/JSON and the migration is straightforward as most patterns map one-to-one.
What stays the same
- REST API over HTTPS with JSON request bodies (when using SESv2; SES v1 form-encoded callers will move to JSON)
- Domain authentication: Paubox verifies your sending domain with an SPF record
- SMTP as an alternative to the HTTP API
- Webhook-based event notifications for delivery status
- Per-domain sending configuration
Key differences
Send a single email
Note:SES uses AWS SigV4 over the AWS credential chain (
AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_REGION, or an IAM role). Paubox uses a single Bearer token. After cutover, remove the AWS SDK dependency and any AWS credentials scoped to ses:SendEmail from your runtime environment.SMTP configuration
Webhook event mapping
SES does not push HTTP webhooks directly; bounces, complaints, and deliveries are published to an SNS topic that fans out to an HTTPS subscription. Paubox replaces both layers with a direct HTTPS POST to your endpoint.Note:Click counts are available by polling
GET /message_receipt?sourceTrackingId=...; they are not delivered as a push webhook event. The receipt includes them only when Click Tracking is turned on in Settings > Email API. It is off by default.Note:Paubox webhooks POST directly to your HTTPS endpoint. There is no intermediary SNS topic, so the JSON envelope is flatter than the SES → SNS → subscription payload. Configure endpoints in the Paubox dashboard under Settings → Webhooks. See the Webhooks reference for the payload shape.
Template migration
If you use SES templates (CreateTemplate / SendTemplatedEmail / SendBulkTemplatedEmail), recreate each one as a Paubox Dynamic Template. Both systems use Handlebars-style {{variable}} syntax, so most template bodies port verbatim.
1
Export each SES template
Run
aws ses get-template --template-name <name> (or aws sesv2 get-email-template) and capture the HtmlPart field. A Paubox dynamic template holds only a name and an HTML body. Paubox generates the plain-text part from the HTML when it sends, so TextPart isn’t needed. Move the Subject into each send’s headers.subject; template variables are not rendered in the subject.2
Create the Paubox Dynamic Template
POST each template to
/dynamic_templates with its name as data[name] and the HtmlPart as data[body]. See the Dynamic templates reference for the request format.3
Switch from SendTemplatedEmail to templated messages
Replace
SendTemplatedEmail / SendBulkTemplatedEmail calls with POST /templated_messages, passing the template name in data.template_name and the variable values as a JSON-encoded string in data.template_values. /bulk_messages does not accept templates, so send one templated request per message. See the Dynamic templates guide for an example.Migration checklist
1
Sign a BAA with Paubox
Required before go-live. Contact Paubox to initiate the Business Associate Agreement.
2
Create an account and verify your sending domain
Add your domain on the Settings > Domains page, add
include:_spf.paubox.com to your domain’s SPF record as shown on the domain’s page, then click Verify. The record shown adds the Paubox include to your existing SPF entries rather than replacing them, so SES keeps working while you migrate. See the Quickstart guide for step-by-step instructions.3
Generate a Paubox API key
From the Settings > API Keys page, generate an API key with the Paubox Email API scope for your verified domain. All requests use the base URL
https://api.paubox.com/v1/email.4
Replace the AWS SDK call with a Paubox request
Remove
@aws-sdk/client-ses / @aws-sdk/client-sesv2 (or the boto3 / Aws::SESV2 equivalent) and call Paubox via fetch / one of the Paubox SDKs. Restructure the request body to use the data.message shape shown above.5
Remove AWS credentials from runtime config
Drop
AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_REGION, and any IAM role permissions scoped to ses:SendEmail / ses:SendRawEmail / ses:SendBulkEmail.6
Update SMTP credentials
If you use the SMTP path, update
host to smtp.paubox.com, set username to the literal string apikey, and password to your Paubox API key. Delete the IAM user that was created for SES SMTP credentials.7
Recreate SES templates as Paubox Dynamic Templates
See Template migration above.
8
Tear down the SNS topic and HTTPS subscription
Remap your bounce / complaint / delivery handler to the Paubox webhook payload using the event mapping table above, then delete the SNS topic and configuration-set event destination used for SES feedback.
9
Remove any TLS policy overrides
Paubox applies TLS by default; remove
TlsPolicy: OPTIONAL or TlsPolicy: REQUIRE from any SES configuration set you were referencing.10
Send a test message
Confirm delivery using the Get message receipt endpoint with the
sourceTrackingId returned from your test send.11
Remove SES DNS records
Once traffic has fully moved to Paubox, remove SES’s SPF entries and DKIM records from your DNS. Keep
include:_spf.paubox.com. Paubox Email API domains need no DKIM record of their own.12
Revoke AWS credentials
Once traffic has fully moved to Paubox, delete the IAM user and access keys used by the SES integration.
Next steps
Quickstart guide
Full setup walkthrough from account creation to first send
Webhooks reference
Configure delivery event notifications
Batch send
Send multiple messages in one request (recommended max 50)
SMTP API
Connect via SMTP instead of REST