Migrar do SendGrid

Este guia mostra a correspondência entre os conceitos, as chamadas à API, os webhooks, as supressões e os templates do SendGrid 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

Atualizar as chamadas à API

O POST /v3/mail/send do SendGrid passa a ser POST /v2/emails. A requisição é mais simples: não há personalizations, e os endereços são strings simples.

curl https://api.sendgrid.com/v3/mail/send \
  -H "Authorization: Bearer $SENDGRID_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "personalizations": [{ "to": [{ "email": "ada@example.com" }] }],
    "from": { "email": "hello@acme.com", "name": "Acme" },
    "subject": "Your receipt",
    "content": [
      { "type": "text/plain", "value": "Thanks for your order." },
      { "type": "text/html", "value": "<p>Thanks for your order.</p>" }
    ]
  }'

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>"
  }'

Cada destinatário de uma requisição do Emailit vira um e-mail próprio, com o seu próprio ID. Para enviar variáveis diferentes para pessoas diferentes, o que o SendGrid faz com várias personalizations, envie uma requisição por destinatário. 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ê o cabeçalho X-SMTPAPI. Remova-o e configure o rastreamento no domínio. Consulte Configurações SMTP.

Correspondência dos eventos de webhook

Assim como o SendGrid, o Emailit envia um array JSON de eventos. Os campos são diferentes:

• O nome do evento fica em type, e o e-mail fica em data.object. Use data.object.id (o ID em_ da resposta do envio) em vez de sg_message_id, e data.object.to em vez de email.
• Os seus valores de meta voltam em data.object.meta.
• O Emailit assina as requisições com HMAC-SHA256, em vez da chave pública ECDSA do SendGrid. Verifique X-Emailit-Signature com 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. No SendGrid, exporte Bounces, Spam Reports, Invalid Emails e Global Unsubscribes, pelas páginas de supressão ou pelos endpoints de API /v3/suppression/*. Os bloqueios (Blocks) costumam ser temporários, então você pode deixá-los de fora.

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

   CSV

   email,type,reason
   old-address@example.com,recipient,sendgrid bounce
   angry@example.com,recipient,sendgrid spam report

   Use o tipo recipient para endereços que nunca devem receber e-mails. Ele bloqueia envios pela API, por SMTP e de campanhas. Os tipos bounce, complaint e unsubscribe só bloqueiam campanhas.

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, então divida as listas maiores. Os duplicados são ignorados.

Para quem se descadastrou de grupos de e-mail de marketing, importe essas pessoas como contatos marcados como unsubscribed, em vez de suprimi-las de todos os e-mails. Consulte Gerenciar supressões.

Migrar os templates

Exporte o HTML de cada dynamic template do SendGrid e depois importe-o em Email Marketing›Templates ou crie-o com a API de templates. Dê a cada template um alias, como receipt, e envie-o com "template": "receipt".

Os dois usam chaves duplas, mas o Temple é menor que o Handlebars:

Consulte Temple e Importar e exportar templates.

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 os CNAMEs de domain authentication ou de link branding do SendGrid. Mantenha o seu registro DMARC. Depois da virada, remova os CNAMEs do SendGrid. Consulte Registros DNS.

Se você usava o Inbound Parse, aponte o registro MX do hostname de parse para o Emailit. Para manter o mesmo hostname, como parse.acme.com, defina o inbound_key do domínio como parse pela API. 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ê