Pular para o conteúdo
Docs

Guia

Migre do SparkPost (agora Bird Email) para o Emailit. Converta as transmissions e os substitution data, troque as configurações SMTP_Injection e migre os event webhooks, as supressões, os templates e o DNS.

Atualizado em 23 de out. de 2026

Este guia mostra a correspondência entre os conceitos, as chamadas à API, os webhooks, as supressões e os templates do SparkPost e os equivalentes no Emailit. O SparkPost agora faz parte da Bird e é vendido como Bird Email, e a API do SparkPost em api.sparkpost.com continua funcionando. Este guia trata dessa API. Leia antes Migrar para o Emailit para conhecer a ordem geral e saber como usar os dois provedores em paralelo.

Conceitos

SparkPost Emailit
Primary account e subaccounts Conta e workspaces. Cada workspace tem os seus próprios domínios, chaves, membros e créditos.
Contas nos EUA e na UE, em hosts de API separados Um único host de API, api.emailit.com
API keys com grants Chaves de API: Full Access, ou Sending Only, que pode ser restrita a um domínio
Sending domains Domínios de envio
Bounce domains O return path emailit.<your domain>, que todo domínio tem
Tracking domains Subdomínio de rastreamento, como go.acme.com
Transmissions E-mails, uma requisição por mensagem
Stored recipient lists Listas de contatos e campanhas
Templates e snippets Templates com alias e versões. Não há snippets.
Event webhooks Webhooks
Inbound domains e relay webhooks Recebimento de e-mails
Suppression list Supressões
metadata, tags, campaign_id meta
options.sandbox Não há modo de teste. Os workspaces novos ficam no modo sandbox e só entregam para membros do workspace.
IP pools IPs dedicados sob solicitação

Atualizar as chamadas à API

O POST /api/v1/transmissions do SparkPost passa a ser POST /v2/emails. O conteúdo passa para o nível superior do corpo, e os destinatários viram to, cc e bcc:

Antes: SparkPost
curl https://api.sparkpost.com/api/v1/transmissions \
  -H "Authorization: $SPARKPOST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "recipients": [{ "address": { "email": "ada@example.com" } }],
    "content": {
      "from": { "email": "hello@acme.com", "name": "Acme" },
      "subject": "Your receipt",
      "text": "Thanks for your order.",
      "html": "<p>Thanks for your order.</p>"
    }
  }'
Depois: Emailit
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>"
  }'
SparkPost Emailit
Authorization: <API key>, sem Bearer Authorization: Bearer secret_…
content.from, uma string ou { email, name } from: "Name <email>"
recipients[].address to, uma string ou um array de até 50 endereços
Cc e Bcc como destinatários extras com header_to e um cabeçalho CC cc e bcc
content.reply_to reply_to
content.subject, content.text, content.html subject, text, html
content.headers headers
content.attachments[] com name, type, data attachments[] com filename, content_type, content
content.inline_images[] attachments[] com um content_id, referenciado como cid: no HTML
content.template_id template: um alias envia a versão publicada, e um ID tem_ envia exatamente essa versão, seja rascunho ou não
substitution_data variables
metadata, recipients[].tags, campaign_id meta, um objeto com valores em string, devolvido nos eventos de webhook
options.open_tracking, options.click_tracking tracking: { "loads": true, "clicks": true }
options.start_time (até 3 dias de antecedência) scheduled_at (ISO 8601 ou inglês simples)
options.transactional Não é necessário. Os e-mails da API nunca recebem cabeçalhos List-Unsubscribe, a menos que você os adicione.
content.email_rfc822 Envie a mensagem MIME pelo SMTP relay
recipients: { "list_id": "…" } Uma campanha para uma lista de contatos
Cabeçalho Idempotency-Key Cabeçalho Idempotency-Key, mantido por 24 horas
Resposta com o id da transmission e as contagens de destinatários 200 com id (em_…), status: "accepted" e, para vários destinatários, ids, com um ID para cada um

O SparkPost envia uma mensagem separada para cada destinatário de uma transmission, e ninguém vê os outros endereços. No Emailit, todos em to e cc aparecem nos cabeçalhos de cada cópia. Para manter os destinatários separados, ou para dar a cada um os seus próprios substitution_data, envie uma requisição por destinatário. Você recebe os IDs dos e-mails na hora, em vez de procurar os IDs das mensagens em eventos posteriores. Consulte Enviar um e-mail.

Mudar as configurações SMTP

Configuração SparkPost Emailit
Host smtp.sparkpostmail.com, ou smtp.eu.sparkpostmail.com smtp.emailit.com
Porta 587 ou 2525 (STARTTLS) 587, 2587, 2525 ou 25 (STARTTLS), 465 (TLS)
Usuário SMTP_Injection emailit
Senha Uma chave de API com a permissão Send via SMTP A sua chave de API do Emailit

O Emailit não lê o cabeçalho X-MSYS-API. Remova-o. Coloque os endereços de Cc e Bcc na mensagem como destinatários normais, configure o rastreamento no domínio e use a API quando precisar de metadados. Consulte Configurações SMTP.

Correspondência dos eventos de webhook

Evento do SparkPost Evento do Emailit
injection email.accepted (somente API)
delivery email.delivered
delay email.attempted
bounce, out_of_band email.bounced
policy_rejection email.suppressed, quando o endereço tem uma supressão recipient
generation_failure, generation_rejection Nenhum evento. Problemas como um template desconhecido são erros na resposta da API.
spam_complaint email.complained
open, initial_open email.loaded
click email.clicked
list_unsubscribe, link_unsubscribe email.unsubscribed, somente para e-mails de campanha
Relay webhook email.received; depois, busque o conteúdo com GET /emails/{id}

O formato da requisição muda:

  • Os dois enviam um array JSON de eventos. O SparkPost envolve cada evento em msys e em uma classe como message_event. O Emailit coloca o nome em type e o e-mail em data.object, com até 100 eventos por requisição.
  • Use data.object.id, o ID em_ da resposta do envio, em vez de message_id e transmission_id, e data.object.to em vez de rcpt_to. Os seus valores de meta, que substituem rcpt_meta e rcpt_tags, ficam em data.object.meta.
  • Em email.loaded e email.clicked, data.object é o carregamento ou o clique. Use data.object.email_id para obter o ID do e-mail, e data.object.email.rcpt_to e data.object.email.meta para obter o destinatário e os seus valores de meta.
  • O SparkPost protege os webhooks com autenticação básica ou OAuth 2.0, sem assinatura. O Emailit assina cada requisição: verifique X-Emailit-Signature com X-Emailit-Timestamp e o seu segredo whsec_. Consulte Assinatura das requisições.
JavaScript
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 a lista de supressão com GET /api/v1/suppression-list?per_page=10000&cursor=initial e siga o cursor até ter todas as páginas. Ela inclui as entradas das suas subaccounts, cada uma com o subaccount_id dela.

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

    Entrada do SparkPost Tipo no Emailit
    transactional, ou os dois tipos recipient, que bloqueia envios pela API, por SMTP e de campanhas
    Apenas non_transactional unsubscribe, que bloqueia campanhas, mas ainda deixa passar os e-mails transacionais
    open_tracking Deixe de fora. Essa entrada não bloqueia o envio.
    CSV
    email,type,reason
    old-address@example.com,recipient,sparkpost bounce rule
    left@example.com,unsubscribe,sparkpost unsubscribe link
  3. Em Email APISuppressions, 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.

Se você usava subaccounts, divida o arquivo por subaccount e importe cada parte no workspace correspondente. Consulte Gerenciar supressões.

Migrar os templates

Obtenha cada template publicado com GET /api/v1/templates/{id}?draft=false, que retorna content.html, content.text e content.subject. Importe-o em Email MarketingTemplates ou crie-o com a API de templates e use o ID do template no SparkPost como alias, se ele se encaixar no formato de alias: letras minúsculas, números, - e _.

Converta a linguagem de templates do SparkPost para o Temple:

SparkPost Emailit (Temple)
{{name}}, {{order.total}} Igual
{{address.name}}, {{address.email}} (o destinatário) Passe esses valores em variables, por exemplo como name e email
{{{html_block}}} {{html_block}}. O Temple nunca escapa HTML, então escape você mesmo o que vier dos usuários.
{{name or 'Customer'}} {{name|"Customer"}}
{{if plan}}…{{else}}…{{end}} {{#if plan}}…{{else}}…{{/if}}
{{if plan == 'pro'}}, {{elseif}}, and, or Não suportado. Passe um booleano como is_pro e use {{#if is_pro}}.
{{each items}}…{{end}} Não suportado. Renderize a lista no seu código e passe-a como uma única variável.
render_snippet(), render_dynamic_content() Não suportado. Coloque o conteúdo no template ou passe-o como uma variável.
substitution_data variables

Consulte Temple e Importar e exportar templates.

Alterar o DNS

Adicione o seu domínio em Email APIDomains 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 SparkPost (um seletor como scph0316._domainkey), com o CNAME do bounce domain nem com o CNAME do tracking domain dele. Mantenha o seu registro DMARC. Consulte Registros DNS.

Se o tracking domain ou o inbound domain do SparkPost já usar o nome go ou inbound, escolha outros nomes para o Emailit com tracking_key e inbound_key. Consulte Configurar um domínio de rastreamento personalizado e Configurar o recebimento de e-mails.

Depois da virada, remova os registros DKIM, de bounce e de rastreamento do SparkPost. Se você recebe e-mails com relay webhooks, mude antes para um subdomínio de recebimento do Emailit e depois remova os registros MX rx1, rx2 e rx3 do SparkPost.

Próximos passos

Esta página foi útil?

Obrigado pelo feedback.

Obrigado, lemos todas as mensagens.