Guia
Migrar do SparkPost
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.
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:
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>"
}
}'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
msyse em uma classe comomessage_event. O Emailit coloca o nome emtypee o e-mail emdata.object, com até 100 eventos por requisição. - Use
data.object.id, o IDem_da resposta do envio, em vez demessage_idetransmission_id, edata.object.toem vez dercpt_to. Os seus valores demeta, que substituemrcpt_metaercpt_tags, ficam emdata.object.meta. - Em
email.loadedeemail.clicked,data.objecté o carregamento ou o clique. Usedata.object.email_idpara obter o ID do e-mail, edata.object.email.rcpt_toedata.object.email.metapara obter o destinatário e os seus valores demeta. - 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-SignaturecomX-Emailit-Timestampe o seu segredowhsec_. 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
-
Exporte a lista de supressão com
GET /api/v1/suppression-list?per_page=10000&cursor=initiale siga o cursor até ter todas as páginas. Ela inclui as entradas das suas subaccounts, cada uma com osubaccount_iddela. -
Monte um único CSV com as colunas
email,type,reason:Entrada do SparkPost Tipo no Emailit transactional, ou os dois tiposrecipient, que bloqueia envios pela API, por SMTP e de campanhasApenas non_transactionalunsubscribe, que bloqueia campanhas, mas ainda deixa passar os e-mails transacionaisopen_trackingDeixe de fora. Essa entrada não bloqueia o envio. email,type,reason old-address@example.com,recipient,sparkpost bounce rule left@example.com,unsubscribe,sparkpost unsubscribe link -
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
- Checklist para entrar em produção
- Configurar webhooks
- Migração prioritária: deixe os engenheiros do Emailit fazerem a migração com você