Do Amazon SES para a Postal, com o SES por baixo

Antes de mudar qualquer coisa, liste o que o seu sistema usa no SES. Cada item tem um lugar na Postal. As identidades do SES valem para uma região só, então anote as regiões em que você envia.

Adicione o domínio em Domínios (ou com POST /domains), escolha a região e publique os registros que a Postal mostra. Ela confere o DNS sozinha por até 72 horas, mostra o status de cada registro e explica o que está errado. O domínio pode continuar verificado no SES ao mesmo tempo: os nomes dos registros são diferentes.

• Se o seu Return-Path no SES já se chama postal, escolha outro nome na Postal com custom_return_path, para não misturar os registros.
• Para migrar aos poucos, use um subdomínio só de e-mail, como mail.exemplo.com.br.
• A Postal avisa pelo webhook domain.updated quando o domínio vira verified. Veja Domínios e DNS.

Crie uma chave de API (acesso total, ou só de envio e restrita ao domínio) e troque o SendEmail do SDK da AWS por POST /emails. A resposta traz o id do e-mail, no lugar do 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: 'Seu pedido saiu para entrega' },-     Body: { Html: { Data: '<p>O pedido #10482 está a caminho.</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: 'Seu pedido saiu para entrega',+     html: '<p>O pedido #10482 está a caminho.</p>',+     tags: [{ name: 'category', value: 'shipping' }],+   }),+ })

• Os erros chegam com o status HTTP e um JSON {statusCode, name, message}. A cota responde 429 e a pausa por reputação, 403 sending_paused.
• Prefere um SDK? Os da Postal (Node.js, PHP e Laravel) e o da Resend, apontado para a Postal, usam a mesma API. Veja SDKs e CLI e a referência de e-mails.

Sistemas que falam SMTP, como WordPress, ERPs e plataformas de loja, mudam quatro campos: servidor, porta, usuário e senha. A senha deixa de ser a senha SMTP derivada de uma chave do IAM e passa a ser uma chave de API da Postal.

- MAIL_HOST=email-smtp.us-east-1.amazonaws.com- MAIL_PORT=587- MAIL_USERNAME=<usuário SMTP do SES>- MAIL_PASSWORD=<senha SMTP do SES>+ MAIL_HOST=smtp.postal.so+ MAIL_PORT=587+ MAIL_USERNAME=postal+ MAIL_PASSWORD=ps_sua_chave

• O TLS é obrigatório nos dois. Na Postal, a autenticação (AUTH PLAIN ou AUTH LOGIN) vem sempre depois do TLS.
• O SMTP da Postal não tem etiquetas, agendamento nem templates: para isso, use a API. Se o seu sistema manda os cabeçalhos X-SES-CONFIGURATION-SET ou X-SES-MESSAGE-TAGS, tire-os, porque são do SES.
• Os envios por SMTP seguem as mesmas regras da API (domínio verificado, cotas e supressão) e aparecem em E-mails e Logs. Cada mensagem aceita pode ter até 40 MB e 50 destinatários. Veja o guia de SMTP.

No SES, o caminho dos eventos é seu: configuration set, destino de evento, tópico SNS e uma assinatura que o seu código precisa receber. Na Postal você cadastra uma URL HTTPS em Webhooks e escolhe os eventos. Cada entrega é assinada com o signing_secret do endpoint e repetida se falhar.

- 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+ }

• O identificador que você guarda passa a ser o id devolvido por POST /emails (data.email_id no webhook), e não o MessageId do SES.
• As etiquetas voltam em data.tags como objeto, por exemplo {"category": "shipping"}.
• A Postal tem ainda eventos que o SES não tem, como email.scheduled, email.suppressed, email.received e domain.updated.
• Qualquer resposta 2xx confirma a entrega. Tire o tópico SNS só depois de virar todo o tráfego, porque os e-mails que ainda saem pelo SES continuam gerando eventos lá. Veja Webhooks.

Quem já deu bounce permanente ou reclamou no SES não deve receber de novo. Exporte a lista de supressão da sua conta e importe na Postal antes do primeiro envio e antes de importar contatos, porque um endereço suprimido nunca vira contato.

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
}

• A lista do SES vale para a conta e para a região. Exporte uma vez por região em que você enviava. No console, ela fica em Configuration > Suppression list.
• O SES guarda o endereço exatamente como entrou, com maiúsculas e minúsculas. A Postal compara sem diferenciar, então o comando acima passa tudo para minúsculas e tira os repetidos.
• Na Postal, os endereços entram com a origem manual: a diferença entre BOUNCE e COMPLAINT do SES não é guardada.
• Precisa de uma chave de acesso total. Para poucos endereços, o painel aceita um por vez em Supressões. Veja a referência de supressões.

Vire um fluxo de cada vez. Comece pelos endereços de teste e por você mesmo, acompanhe em E-mails e Logs e só então passe o resto. Mantenha o SES ligado até os eventos dos últimos e-mails antigos chegarem.

• Os endereços de teste (delivered@, bounced@, complained@, suppressed@ e [email protected]) não usam a cota nem pesam na reputação. Dependem do plano.
• Veja os valores atuais em Preços e em Limites.