Guia
Migrar do Elastic Email
Migre do Elastic Email para o Emailit. Faça a correspondência das chamadas às APIs v4 e v2, das credenciais SMTP e das notificações, converta os campos de mesclagem e migre supressões, contatos e campanhas.
Este guia mostra a correspondência entre os conceitos, as chamadas à API, as notificações, as supressões, os templates e os contatos do Elastic Email 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
| Elastic Email | Emailit |
|---|---|
| Conta e subaccounts | Conta e workspaces. Cada workspace tem os seus próprios domínios, chaves, membros e créditos. |
| Chaves de API com níveis de acesso | Chaves de API: Full Access, ou Sending Only, que pode ser restrita a um domínio |
| Credenciais SMTP | A sua chave de API, usada como senha do SMTP |
| Domínios verificados e endereços de remetente verificados | Domínios de envio. Remetentes de um único endereço não estão disponíveis. |
| Channels e valores de postback | meta |
| Templates, identificados pelo nome | Templates com alias e versões |
| Campos de mesclagem e scripts de template | Temple: variáveis, valores padrão e condicionais |
| Notificações web por HTTP | Webhooks |
| Inbound routes | Recebimento de e-mails |
| Supressões e status de contato que bloqueiam o envio | Supressões |
| Contatos e listas | Contatos e listas de contatos |
| Segmentos | Escolha listas de contatos e deixe outras de fora em cada campanha. Os segmentos estão em alfa e disponíveis apenas para a equipe do Emailit. |
| Campanhas e automações | Campanhas e automações (beta) |
| Formulários | Formulários (acesso antecipado), ou a URL de inscrição de uma lista de contatos |
| Verificação de e-mails | Verificação de e-mails |
| IPs privados e IP pools | IPs dedicados sob solicitação |
O Elastic Email adiciona um link de descadastro a todos os e-mails, incluindo os envios pela API e por SMTP. O Emailit adiciona cabeçalhos List-Unsubscribe apenas às campanhas e aos e-mails de marketing das automações, e você mesmo adiciona o link visível com {{unsubscribe_url}}. Se você envia newsletters ou outros e-mails em massa pela API ou por SMTP, adicione o seu próprio link e os cabeçalhos List-Unsubscribe. Consulte Cabeçalhos e metadados.
Atualizar as chamadas à API
O POST /v4/emails/transactional do Elastic Email passa a ser POST /v2/emails. O corpo é plano, os nomes dos campos ficam em minúsculas e a chave passa para um cabeçalho Authorization:
curl https://api.elasticemail.com/v4/emails/transactional \
-H "X-ElasticEmail-ApiKey: $ELASTICEMAIL_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"Recipients": { "To": ["ada@example.com"] },
"Content": {
"From": "Acme <hello@acme.com>",
"Subject": "Your receipt",
"Body": [
{ "ContentType": "HTML", "Content": "<p>Thanks for your order.</p>" },
{ "ContentType": "PlainText", "Content": "Thanks for your order." }
]
}
}'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>"
}'| Elastic Email (API v4) | Emailit |
|---|---|
Cabeçalho X-ElasticEmail-ApiKey |
Authorization: Bearer secret_… |
Content.From |
from |
Recipients.To, CC, BCC |
to, cc, bcc, até 50 cada |
Content.ReplyTo |
reply_to |
Content.Subject |
subject |
Content.Body[] com ContentType HTML e PlainText |
html e text |
Content.Headers |
headers |
Content.Attachments[] com BinaryContent, Name, ContentType |
attachments[] com content, filename, content_type |
Content.AttachFiles (arquivos enviados antes) |
attachments[] com uma url que o Emailit baixa |
Content.TemplateName |
template, um alias ou ID de template |
Content.Merge |
variables |
Options.ChannelName, Content.Postback |
meta, devolvido nos eventos de webhook |
Options.TrackOpens, Options.TrackClicks |
tracking: { "loads": true, "clicks": true } |
Options.TimeOffset (minutos) |
scheduled_at (ISO 8601 ou inglês simples) |
Options.PoolName |
Não é necessário. Um IP dedicado envia todos os e-mails do workspace dele. |
Content.Utm |
Adicione parâmetros UTM aos seus links. As campanhas os adicionam para você. |
POST /v4/emails com Recipients[].Fields (mesclagem em massa) |
Uma requisição por destinatário, cada uma com as suas variables |
Cabeçalho Idempotency-Key |
Cabeçalho Idempotency-Key, mantido por 24 horas |
Resposta com TransactionID e MessageID |
200 com id (em_…), status: "accepted" e, para vários destinatários, ids, com um ID para cada um |
Se você ainda usa a API v2 (/v2/email/send com um parâmetro apikey), faça a correspondência dos campos de formulário dela da mesma forma: from e fromName viram from, bodyHtml e bodyText viram html e text, os campos merge_* viram variables e template vira template. Na v2, cada endereço em to recebe uma mensagem separada, como em Bcc. No Emailit, os destinatários em to veem uns aos outros no cabeçalho To, então envie uma requisição por destinatário para mantê-los separados. Consulte Enviar um e-mail.
Mudar as configurações SMTP
| Configuração | Elastic Email | Emailit |
|---|---|---|
| Host | smtp.elasticemail.com |
smtp.emailit.com |
| Porta | 2525, 587 ou 25 (STARTTLS), 465 (TLS) |
587, 2587, 2525 ou 25 (STARTTLS), 465 (TLS) |
| Usuário | O nome da credencial SMTP, um endereço de e-mail | emailit |
| Senha | O token da credencial SMTP | A sua chave de API do Emailit |
O Emailit não lê os cabeçalhos de controle do Elastic Email, como X-ElasticEmail-Channel, X-ElasticEmail-Postback, IsTransactional, trackopens ou trackclicks. Remova-os e configure o rastreamento no domínio. Consulte Configurações SMTP.
Correspondência dos eventos de webhook
| Notificação do Elastic Email | Evento do Emailit |
|---|---|
Sent (o servidor do destinatário aceitou a mensagem) |
email.delivered |
Opened |
email.loaded |
Clicked |
email.clicked |
Error |
email.bounced para falhas permanentes. As falhas temporárias enviam email.attempted enquanto o Emailit faz novas tentativas. |
AbuseReport |
email.complained |
Unsubscribed |
email.unsubscribed, somente para e-mails de campanha |
| Inbound route que notifica uma URL | email.received; depois, busque o conteúdo com GET /emails/{id} |
O Emailit também envia email.accepted quando a API aceita um e-mail, e email.suppressed quando uma supressão recipient bloqueia um endereço. Consulte Tipos de evento.
O formato da requisição muda:
- O Elastic Email envia um evento por requisição, na query string ou como um objeto JSON plano. O Emailit envia um array JSON de até 100 eventos, então percorra o corpo em um loop.
- O nome do evento passa de
statusparatype, e o e-mail fica emdata.object. Usedata.object.id, o IDem_da resposta do envio, em vez demessageid, edata.object.toem vez deto. Os seus valores demeta, que substituemchannelepostback, 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 Emailit assina cada requisição. Verifique
X-Emailit-Signature, o HMAC-SHA256 em hexadecimal de<timestamp>.<raw body>, comX-Emailit-Timestampe o seu segredowhsec_. A assinatura opcional do Elastic Email também usa segredoswhsec_, mas assina uma string diferente, então atualize o seu código de verificação. 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 os endereços que o Elastic Email bloqueia, em Suppressions no painel ou pela API (
/v4/suppressions/bounces,/complaintse/unsubscribes). -
Monte um único CSV com as colunas
email,type,reason:Status no Elastic Email Tipo no Emailit Invalid ( Bounced)recipientComplaint ( Abuse)recipientUnsubscribed unsubscribe, que bloqueia campanhas, mas ainda deixa passar os e-mails transacionais. Userecipientpara bloquear todos os e-mails.email,type,reason old-address@example.com,recipient,elastic email bounced left@example.com,unsubscribe,elastic email unsubscribed -
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.
Consulte Gerenciar supressões.
Migrar os contatos e as campanhas
Exporte os seus contatos em Contacts (selecione-os e depois use More actions > Export) ou com POST /v4/contacts/export, e exporte cada lista para a qual você envia campanhas. Depois, traga-os de acordo com o status:
| Status no Elastic Email | Para onde vai |
|---|---|
| Engaged, Active | Importe na lista de contatos correspondente em Email MarketingContacts com Import. |
| Transactional | Deixe-os fora das listas de contatos. Eles nunca se inscreveram nos seus e-mails de marketing. |
| Invalid, Complaint, Unsubscribed | A lista de supressão, como acima. |
| Inactive, Stale, Not Confirmed | Deixe-os de fora. |
Crie campos personalizados para os seus campos de contato antes de importar e divida os arquivos em partes de até 2.500 linhas. A importação adiciona todas as pessoas do arquivo como inscritas, então importe apenas quem deve receber as suas campanhas. Consulte Importar e exportar contatos.
Recrie as suas campanhas e automações em Email MarketingCampaigns e Automations, a partir dos templates importados.
Migrar os templates
Copie o HTML de cada template com Edit as HTML no Elastic Email, ou obtenha-o com GET /v4/templates/{name}, que o retorna em Body. Importe-o em Email MarketingTemplates ou crie-o com a API de templates e use o nome do template como alias, se ele se encaixar no formato de alias: letras minúsculas, números, - e _.
Os campos de mesclagem do Elastic Email usam chaves simples, e o Temple usa chaves duplas. Os campos com chaves simples que ficarem em um template são enviados como texto simples, então converta todos:
| Elastic Email | Emailit (Temple) |
|---|---|
{firstname}, {lastname}, {email} |
{{first_name}}, {{last_name}}, {{email}} nas campanhas. Nos envios pela API, os nomes que você passa em variables. |
{firstname:friend} |
{{first_name|"friend"}} |
{company} ou outro campo personalizado |
{{cf.company}} nas campanhas |
{unsubscribe} |
{{unsubscribe_url}} nas campanhas |
{contactprofile} |
{{manage_subscriptions_url}} nas campanhas |
{view} |
{{webview_url}} nas campanhas |
{accountaddress} e outros campos da conta |
Escreva-os no template ou guarde-os em valores globais |
Scripts de template em {{ … }} |
Não suportado. Calcule os valores no seu código e use {{#if}} para conteúdo condicional. |
Consulte Tags de mesclagem e Temple.
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 api._domainkey do Elastic Email, com o CNAME tracking dele nem com um domínio de bounce personalizado. Mantenha o seu registro DMARC. Consulte Registros DNS.
Depois da virada, remova os registros DKIM e de rastreamento do Elastic Email e o include:_spf.elasticemail.com do seu registro SPF. Se você recebe e-mails com as inbound routes do Elastic Email, mude antes para um subdomínio de recebimento do Emailit. O Emailit recebe em um subdomínio, como inbound.acme.com, então os endereços de recebimento mudam.
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ê