From Amazon SES to Postal, with SES underneath

Before changing anything, list what your system uses in SES. Each item has a place on Postal. SES identities are valid for one region only, so note the regions you send from.

Add the domain under Domains (or with POST /domains), choose the region and publish the records Postal shows. It checks DNS on its own for up to 72 hours, shows the status of each record and explains what is wrong. The domain can stay verified in SES at the same time: the record names are different.

• If your Return-Path in SES is already called postal, pick another name on Postal with custom_return_path, so the records do not get mixed up.
• To migrate gradually, use an email-only subdomain, such as mail.exemplo.com.br.
• Postal notifies you through the domain.updated webhook when the domain becomes verified. See Domains and DNS.

Create an API key (full access, or send-only and restricted to the domain) and replace the AWS SDK's SendEmail with POST /emails. The response carries the email's id, in place of the MessageId.

- import { SESv2Client, SendEmailCommand } from '@aws-sdk/client-sesv2'- - const ses = new SESv2Client({ region: 'us-east-1' })- await ses.send(new SendEmailCommand({-   FromEmailAddress: 'Aurora Cosméticos <[email protected]>',-   Destination: { ToAddresses: ['[email protected]'] },-   Content: { Simple: {-     Subject: { Data: 'Your order is out for delivery' },-     Body: { Html: { Data: '<p>Order #10482 is on its way.</p>' } },-   } },-   EmailTags: [{ Name: 'category', Value: 'shipping' }],- }))+ await fetch('https://api.postal.so/emails', {+   method: 'POST',+   headers: {+     Authorization: `Bearer ${process.env.POSTAL_API_KEY}`,+     'Content-Type': 'application/json',+   },+   body: JSON.stringify({+     from: 'Aurora Cosméticos <[email protected]>',+     to: ['[email protected]'],+     subject: 'Your order is out for delivery',+     html: '<p>Order #10482 is on its way.</p>',+     tags: [{ name: 'category', value: 'shipping' }],+   }),+ })

• Errors arrive with the HTTP status and a JSON {statusCode, name, message}. The quota answers 429 and the pause over reputation answers 403 sending_paused.
• Prefer an SDK? Postal's (Node.js, PHP and Laravel) and Resend's, pointed at Postal, use the same API. See SDKs and CLI and the emails reference.

Systems that speak SMTP, such as WordPress, ERPs and store platforms, change four fields: server, port, username and password. The password stops being the SMTP password derived from an IAM key and becomes a Postal API key.

- MAIL_HOST=email-smtp.us-east-1.amazonaws.com- MAIL_PORT=587- MAIL_USERNAME=<SES SMTP user>- MAIL_PASSWORD=<SES SMTP password>+ MAIL_HOST=smtp.postal.so+ MAIL_PORT=587+ MAIL_USERNAME=postal+ MAIL_PASSWORD=ps_your_key

• TLS is required on both. On Postal, authentication (AUTH PLAIN or AUTH LOGIN) always comes after TLS.
• Postal SMTP has no tags, scheduling or templates: for those, use the API. If your system sends the X-SES-CONFIGURATION-SET or X-SES-MESSAGE-TAGS headers, remove them, because they belong to SES.
• SMTP sends follow the same rules as the API (verified domain, quotas and suppression) and show up in Emails and Logs. Each accepted message can be up to 40 MB with 50 recipients. See the SMTP guide.

On SES, the event path is yours to build: configuration set, event destination, SNS topic and a subscription your code has to receive. On Postal you register an HTTPS URL under Webhooks and pick the events. Each delivery is signed with the endpoint's signing_secret and retried if it fails.

- const message = JSON.parse(body.Message)- if (message.eventType === 'Bounce') {-   const kind = message.bounce.bounceType-   const id = message.mail.messageId- }+ const event = resend.webhooks.verify({ payload: rawBody, headers, webhookSecret })+ if (event.type === 'email.bounced') {+   const kind = event.data.bounce.type+   const id = event.data.email_id+ }

• The identifier you store becomes the id returned by POST /emails (data.email_id in the webhook), not the SES MessageId.
• Tags come back in data.tags as an object, for example {"category": "shipping"}.
• Postal also has events that SES does not, such as email.scheduled, email.suppressed, email.received and domain.updated.
• Any 2xx response confirms delivery. Remove the SNS topic only after moving all traffic, because emails still leaving through SES keep generating events there. See Webhooks.

Anyone who already had a permanent bounce or complained on SES should not receive again. Export your account's suppression list and import it into Postal before the first send and before importing contacts, because a suppressed address never becomes a contact.

aws sesv2 list-suppressed-destinations --region us-east-1 > supressoes-ses.json
# se a resposta trouxer "NextToken", repita com --next-token "<valor>"

jq -r '.SuppressedDestinationSummaries[].EmailAddress' supressoes-ses.json \
  | tr 'A-Z' 'a-z' | sort -u > emails.txt

import { readFileSync } from 'node:fs'

const emails = readFileSync('emails.txt', 'utf8').split('\n').filter(Boolean)
const headers = {
  Authorization: `Bearer ${process.env.POSTAL_API_KEY}`,
  'Content-Type': 'application/json',
}

for (let i = 0; i < emails.length; i += 100) {
  const res = await fetch('https://api.postal.so/suppressions/batch/add', {
    method: 'POST',
    headers,
    body: JSON.stringify({ emails: emails.slice(i, i + 100) }),
  })
  if (!res.ok) throw new Error(await res.text())
  await new Promise((resolve) => setTimeout(resolve, 250)) // respeita o limite do plano
}

• The SES list applies to the account and the region. Export once for each region you sent from. In the console, it is under Configuration > Suppression list.
• SES stores the address exactly as it came in, with upper and lower case. Postal compares case-insensitively, so the command above lowercases everything and removes duplicates.
• On Postal, addresses come in with the manual origin: the difference between SES's BOUNCE and COMPLAINT is not stored.
• It needs a full-access key. For a few addresses, the dashboard accepts one at a time under Suppressions. See the suppressions reference.

Switch one flow at a time. Start with the test addresses and yourself, follow along in Emails and Logs and only then move the rest. Keep SES on until the events for the last old emails arrive.

• The test addresses (delivered@, bounced@, complained@, suppressed@ and [email protected]) do not use the quota or count against reputation. They depend on the plan.
• See current values in Pricing and in Limits.