Do Mailgun para a Postal, campo a campo

Adicione o domínio no painel (ou com POST /domains), crie na sua DNS os registros que a Postal mostra e peça a verificação. Os registros usam nomes próprios, postal._domainkey e o subdomínio postal, então dá para publicá-los ao lado dos do Mailgun e só tirar os antigos depois da virada. Antes, confira que nenhum registro seu já usa esses nomes.

• Região: o Mailgun tem duas URLs, US e EU. Na Postal a URL é uma só e a região é escolhida por domínio: São Paulo (padrão), us-east-1, us-east-2, eu-west-1 ou ap-northeast-1.
• Para sistemas que só enviam, crie uma chave só de envio, restrita ao domínio. O token completo aparece uma única vez, na criação.
• Se o domínio principal já envia pelo Mailgun, use um subdomínio dedicado na Postal.

No Mailgun o domínio vai na URL e os campos vão em form-data. Na Postal o domínio vem do from e o corpo é JSON. A resposta é {"id": "…"}: guarde o ID, que volta nos webhooks como data.email_id e serve para consultar o e-mail em GET /emails/{id}. Com o cabeçalho Idempotency-Key, repetir uma requisição não duplica o envio.

- curl -s --user 'api:$MAILGUN_API_KEY' \-   https://api.mailgun.net/v3/mg.exemplo.com.br/messages \-   -F from='Aurora Cosméticos <[email protected]>' \-   -F [email protected] \-   -F subject='Seu pedido #10482 saiu para entrega' \-   --form-string html='<p>O pedido <b>#10482</b> está a caminho.</p>' \-   -F o:tag='envio'+ curl -X POST https://api.postal.so/emails \+   -H "Authorization: Bearer $POSTAL_API_KEY" \+   -H "Content-Type: application/json" \+   -d '{+     "from": "Aurora Cosméticos <[email protected]>",+     "to": ["[email protected]"],+     "subject": "Seu pedido #10482 saiu para entrega",+     "html": "<p>O pedido <b>#10482</b> está a caminho.</p>",+     "tags": [{"name": "category", "value": "shipping"}]+   }'

- const form = new FormData();- form.append('from', 'Aurora Cosméticos <[email protected]>');- form.append('to', '[email protected]');- form.append('subject', 'Seu pedido #10482 saiu para entrega');- form.append('html', '<p>O pedido <b>#10482</b> está a caminho.</p>');- form.append('o:tag', 'envio');- const auth = Buffer.from('api:' + process.env.MAILGUN_API_KEY).toString('base64');- await fetch('https://api.mailgun.net/v3/mg.exemplo.com.br/messages', {-   method: 'POST',-   headers: { Authorization: `Basic ${auth}` },-   body: form,- });+ const response = await fetch('https://api.postal.so/emails', {+   method: 'POST',+   headers: {+     Authorization: `Bearer ${process.env.POSTAL_API_KEY}`,+     'Content-Type': 'application/json',+     'Idempotency-Key': 'order-10482-shipped',+   },+   body: JSON.stringify({+     from: 'Aurora Cosméticos <[email protected]>',+     to: ['[email protected]'],+     subject: 'Seu pedido #10482 saiu para entrega',+     html: '<p>O pedido <b>#10482</b> está a caminho.</p>',+     tags: [{ name: 'category', value: 'shipping' }],+   }),+ });+ const { id } = await response.json();

Os templates do Mailgun usam uma versão de Handlebars, com condições (if, unless), laços (each), with e equal. Os da Postal só substituem variáveis: {{{NOME}}}, com três chaves, e o valor precisa ser texto ou número. Não há condições, laços nem objetos aninhados. Quando o seu template depende de lógica, mova a lógica para o código: escolha entre dois templates ou monte o HTML você mesmo e mande em html.

• Na Postal você edita um rascunho e publica; os envios usam sempre a última versão publicada, e as versões antigas podem ser restauradas.
• No HTML os valores são escapados. Uma variável sem valor e sem valor padrão (fallback_value) devolve erro 422.
• Declare as variáveis ao criar o template: até 50, com tipo texto ou número.

- <h1>Olá, {{name}}!</h1>- <p>Seu pedido: {{order}}</p>+ <h1>Olá, {{{NAME}}}!</h1>+ <p>Seu pedido: {{{ORDER}}}</p>

- -F template='pedido-enviado' \- -F t:variables='{"name": "Ana", "order": "10482"}'+ "template": {+   "id": "pedido-enviado",+   "variables": {"NAME": "Ana", "ORDER": "10482"}+ }

Se algum sistema envia por SMTP, troque servidor, usuário e senha. O SMTP faz parte do plano. As mensagens passam pelas mesmas regras da API (domínio verificado, cotas, lista de supressão) e aparecem em E-mails e Logs.

• Limites da Postal por mensagem: 40 MB e 50 destinatários. Quem passar disso recebe erro; divida o envio.

- host: 'smtp.mailgun.org',- port: 587,- secure: false,- auth: { user: '[email protected]',-   pass: process.env.MAILGUN_SMTP_PASSWORD },+ host: 'smtp.postal.so',+ port: 465,+ secure: true,+ auth: { user: 'postal', pass: process.env.POSTAL_API_KEY },

Crie o endpoint na Postal e guarde o signing_secret. A assinatura muda por completo: no Mailgun ela vem no corpo e usa uma chave de assinatura de webhooks; na Postal vem em cabeçalhos e usa o segredo de cada endpoint. Calcule sobre o corpo exatamente como chegou, sem ler e reescrever o JSON.

• O webhook-id é o mesmo em todas as tentativas: guarde os já processados para descartar duplicatas.
• Responda 2xx logo e processe depois, numa fila.
• Para testar sem enviar de verdade, mande e-mails para os endereços de teste ou use "Enviar evento de teste" no painel.

- const expected = crypto.createHmac('sha256', process.env.MAILGUN_SIGNING_KEY)-   .update(timestamp + token).digest('hex');- if (expected !== signature) return res.sendStatus(401);+ import { verifyWebhook } from 'postal-so';+ const event = verifyWebhook(req.body, req.headers, process.env.POSTAL_WEBHOOK_SECRET);

{
  "type": "email.delivered",
  "created_at": "2026-10-24T13:02:14.120Z",
  "data": {
    "email_id": "019a1b2c-4d5e-7f60-8a9b-0c1d2e3f4a5b",
    "from": "Aurora Cosméticos <[email protected]>",
    "to": ["[email protected]"],
    "subject": "Seu pedido #10482 saiu para entrega",
    "tags": { "category": "shipping" }
  }
}

Faça isso antes do primeiro envio real, para não escrever a quem já pediu para sair nem repetir bounces. A Postal pausa os envios do time se os bounces permanentes passam do limite do nível da reputação da conta (3% numa conta nova) ou as reclamações passam de 0,3%; por isso a lista limpa importa.

Os IDs são diferentes: o ID de um e-mail do Mailgun não existe na Postal. Durante a virada, guarde de qual provedor veio cada e-mail e continue recebendo os webhooks do Mailgun para o que saiu por lá. Mande cada fluxo por um provedor só, para não duplicar nem pausar tudo por causa de e-mails errados.