Migrar do Postmark

Este guia mostra a correspondência entre os conceitos, as chamadas à API, os webhooks, as supressões e os templates do Postmark e os equivalentes no Emailit. Leia antes Migrar para o Emailit para conhecer a ordem geral e saber como usar os dois provedores em paralelo.

Conceitos

Para manter separadas a reputação transacional e a de marketing, envie de domínios ou subdomínios diferentes, como mail.acme.com para recibos e news.acme.com para newsletters.

Atualizar as chamadas à API

O POST /email do Postmark com um X-Postmark-Server-Token passa a ser POST /v2/emails com um bearer token. Os nomes dos campos mudam de PascalCase para snake_case:

curl https://api.postmarkapp.com/email \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "X-Postmark-Server-Token: $POSTMARK_SERVER_TOKEN" \
  -d '{
    "From": "Acme <hello@acme.com>",
    "To": "ada@example.com",
    "Subject": "Your receipt",
    "TextBody": "Thanks for your order.",
    "HtmlBody": "<p>Thanks for your order.</p>",
    "MessageStream": "outbound"
  }'

curl https://api.emailit.com/v2/emails \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "Acme <hello@acme.com>",
    "to": "ada@example.com",
    "subject": "Your receipt",
    "text": "Thanks for your order.",
    "html": "<p>Thanks for your order.</p>"
  }'

O Emailit não tem endpoint de lote. Envie uma requisição por mensagem, cada uma com até 50 destinatários, e adicione um cabeçalho Idempotency-Key para que as novas tentativas sejam seguras. Consulte Enviar um e-mail.

Mudar as configurações SMTP

O Emailit não lê cabeçalhos X-PM-*, como X-PM-Message-Stream ou X-PM-Tag. Remova-os e configure o rastreamento no domínio. Consulte Configurações SMTP.

Correspondência dos eventos de webhook

O Emailit também envia email.accepted quando a API aceita um e-mail, algo para o qual o Postmark não tem webhook.

O formato da requisição muda:

• O Postmark envia um registro por requisição e o identifica em RecordType. O Emailit envia um array JSON de até 100 eventos, com o nome em type e o e-mail em data.object.
• Use data.object.id, o ID em_ da resposta do envio, em vez de MessageID. Os seus valores de meta ficam em data.object.meta.
• Os webhooks do Postmark costumam ser protegidos com credenciais de autenticação básica na URL. O Emailit, em vez disso, assina cada requisição: verifique X-Emailit-Signature com X-Emailit-Timestamp e o seu segredo whsec_. Consulte Assinatura das requisições.

for (const event of req.body) {
  const email = event.data.object;
  if (event.type === 'email.bounced') markBounced(email.to, email.id);
  if (event.type === 'email.complained') unsubscribe(email.to);
}

Migrar as supressões

1. Exporte as supressões de cada message stream do Postmark de onde você envia, pela página de supressões do stream ou pela API de dump de supressões. Inclua hard bounces, reclamações de spam e supressões manuais.

2. Monte um único CSV com as colunas email,type,reason:

   CSV

   email,type,reason
   old-address@example.com,recipient,postmark hard bounce
   angry@example.com,recipient,postmark spam complaint

   Use o tipo recipient para endereços que nunca devem receber e-mails. Ele bloqueia envios pela API, por SMTP e de campanhas. Para pessoas que só cancelaram o recebimento dos seus broadcasts, use o tipo unsubscribe, que bloqueia campanhas, mas ainda deixa passar os e-mails transacionais.

3. Em Email API›Suppressions, selecione Import e envie o arquivo. Cada arquivo pode ter até 10.000 linhas e no máximo 8 MB. Os duplicados são ignorados.

Consulte Gerenciar supressões.

Migrar os templates

Copie o HTML de cada template do Postmark, incluindo o layout dele, e depois importe-o em Email Marketing›Templates ou crie-o com a API de templates. O Emailit não tem layouts, então junte o layout e o conteúdo em um único template. Use o mesmo alias que você usava no Postmark para que as mudanças no seu código sejam pequenas.

Os templates do Postmark usam Mustachio. O Temple cobre valores simples e condições:

O Temple nunca escapa HTML, então escape o que vier dos usuários antes de passar. Um valor ausente é renderizado como string vazia, a menos que você adicione um valor padrão, como {{name|"there"}}. Consulte Temple.

Alterar o DNS

Adicione o seu domínio em Email API›Domains e publique os registros do Emailit. Eles usam nomes próprios (emailit._domainkey, emailit.<domain> e, opcionalmente, go e inbound), então não entram em conflito com o registro DKIM do Postmark nem com o CNAME de return path pm-bounces dele. Mantenha o seu registro DMARC. Depois da virada, remova os registros do Postmark. Consulte Registros DNS.

Se você processa e-mails recebidos com o Postmark, mude para um subdomínio de recebimento do Emailit e atualize os endereços que a sua aplicação divulga. Consulte Configurar o recebimento de e-mails.

Próximos passos

• Checklist para entrar em produção
• Configurar webhooks
• Migração prioritária: deixe os engenheiros do Emailit fazerem a migração com você