Skip to main content

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

Tip:SES SMTP credentials are not the same as your AWS API key; they are derived from a dedicated IAM user via the SES console. After traffic has moved to Paubox, delete that IAM user so the SMTP credential is fully revoked.

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

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