Migrar do SendGrid para a Postal

Cadastre o domínio no painel e crie os registros que ele mostra. Pelos nomes, os registros da Postal não colidem com os do SendGrid, e os dois ficam verificados ao mesmo tempo durante a virada. Se você já tem um _dmarc, mantenha o seu.

• A Postal confere os registros sozinha por até 72 horas e avisa por webhook (domain.updated)
• Crie uma chave de API (ela começa com ps_). Para sistemas que só enviam, use uma chave só de envio, restrita ao domínio

A Postal não aceita o formato /v3/mail/send: a chamada passa a ser POST /emails, com os campos no primeiro nível. Abaixo, o mesmo e-mail nos dois formatos. Quem usa o SDK do SendGrid troca o envio pelo SDK da Postal (Node.js, PHP e Laravel) ou por HTTP, que é JSON com a chave no cabeçalho Authorization.

• O SendGrid responde 202 Accepted; a Postal responde 200 com o id do e-mail. Guarde o id: é ele que aparece nos webhooks e em GET /emails/{id}
• Vários destinatários no mesmo to formam um único e-mail em que todos se veem. Para um e-mail por pessoa, use o envio em lote
• Repetir a chamada com a mesma Idempotency-Key não duplica o envio

Antes: SendGrid

POST https://api.sendgrid.com/v3/mail/send
Authorization: Bearer <chave do SendGrid>

{
  "personalizations": [{
    "to": [{ "email": "[email protected]", "name": "Ana" }],
    "custom_args": { "order_id": "10482" }
  }],
  "from": { "email": "[email protected]", "name": "Loja Exemplo" },
  "subject": "Seu pedido #10482 saiu para entrega",
  "content": [
    { "type": "text/plain", "value": "O pedido #10482 está a caminho." },
    { "type": "text/html", "value": "<p>O pedido <b>#10482</b> está a caminho.</p>" }
  ],
  "categories": ["entrega"]
}

Depois: Postal

POST https://api.postal.so/emails
Authorization: Bearer ps_sua_chave
Idempotency-Key: pedido-10482-saiu

{
  "from": "Loja Exemplo <[email protected]>",
  "to": ["Ana <[email protected]>"],
  "subject": "Seu pedido #10482 saiu para entrega",
  "text": "O pedido #10482 está a caminho.",
  "html": "<p>O pedido <b>#10482</b> está a caminho.</p>",
  "tags": [
    { "name": "category", "value": "entrega" },
    { "name": "order_id", "value": "10482" }
  ]
}

No código

- const sgMail = require('@sendgrid/mail');- sgMail.setApiKey(process.env.SENDGRID_API_KEY);- await sgMail.send({-   to: '[email protected]',-   from: '[email protected]',-   subject, html,- });+ import { Postal } from 'postal-so';+ const postal = new Postal(); // lê POSTAL_API_KEY+ await postal.emails.send({+   from: 'Loja Exemplo <[email protected]>',+   to: '[email protected]',+   subject, html,+ });

A tabela vale para o código novo e como lista de conferência do que o seu sistema usa hoje. As linhas que mudam o jeito de montar o e-mail são as de destinatários em lote, categorias e argumentos personalizados.

Quem manda por SMTP não reescreve nada: troca o servidor, o usuário e a senha. O usuário fixo é postal, e não apikey. A Postal também aceita 2465 (TLS) e 2587 (STARTTLS) para redes que bloqueiam as portas comuns.

• O cabeçalho X-SMTPAPI (category, unique_args, sub, send_at, filters…) não é interpretado pela Postal: ele segue como um cabeçalho comum. O que você usa dele precisa ir para a API
• Os destinatários são os do envelope (RCPT TO), até 50 por mensagem. Quem não aparece em To nem em Cc é tratado como Bcc
• O SMTP da Postal não tem tags, agendamento nem templates. Cotas, lista de supressão, eventos e webhooks são os mesmos da API
• Mensagens até 40 MB; a Postal responde 250 2.0.0 OK queued as <id>, e o id é o do e-mail na API

- Servidor: smtp.sendgrid.net- Porta: 587 (ou 25, 2525, 465)- Usuário: apikey- Senha: a chave de API do SendGrid+ Servidor: smtp.postal.so+ Porta: 465 (TLS direto) ou 587 (STARTTLS)+ Usuário: postal+ Senha: a chave de API da Postal (ps_…)

O SendGrid manda o Event Webhook assinado com uma chave pública (ECDSA); a Postal assina com um segredo por endpoint, no padrão Standard Webhooks. O corpo também muda: um evento por requisição, com o e-mail dentro de data.

import express from 'express';
import { verifyWebhook, PostalWebhookVerificationError } from 'postal-so';

const app = express();
// O corpo precisa chegar cru (Buffer) para a assinatura bater.
app.post('/webhooks/postal', express.raw({ type: 'application/json' }), (req, res) => {
  try {
    const event = verifyWebhook(req.body, req.headers, process.env.POSTAL_WEBHOOK_SECRET);
    if (event.type === 'email.bounced') {
      // descarte o endereço
    }
    res.sendStatus(200);
  } catch (error) {
    if (error instanceof PostalWebhookVerificationError) {
      return res.sendStatus(400);
    }
    throw error;
  }
});

Primeiro a lista de supressão, para não escrever a quem não deve receber. Depois os contatos, se você usa a audiência de marketing. O SendGrid exporta cada tipo de supressão por uma rota própria; a Postal tem uma lista só.

• Faça a importação de contatos depois da supressão: endereços que já estão na lista de supressão são ignorados e não usam o limite de contatos do plano
• Campanhas e automações do marketing precisam ser recriadas na Postal; o que você leva são os contatos e o conteúdo

curl -X POST https://api.postal.so/suppressions/batch/add \
  -H "Authorization: Bearer $POSTAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"emails": ["[email protected]", "[email protected]"]}'

Com o domínio verificado nos dois, passe um fluxo por vez. Convites, redefinições de senha e códigos devem sair por um só caminho de cada vez.

• Os IDs são de cada plataforma: guarde de qual provedor cada e-mail saiu e continue recebendo eventos do SendGrid para o que saiu por lá
• Use tags (por exemplo, provider: postal) para separar os e-mails novos nos webhooks
• Contas novas começam com um teto de 500 e-mails por dia, que cresce com a reputação da conta, e os envios pausam com bounces permanentes acima de 3% a 5%, conforme o nível, ou reclamações acima de 0,3%: suba o volume por etapas