Guia
Migrar do ZeptoMail
Migre do ZeptoMail (agora Zoho CPaaS) para o Emailit. Faça a correspondência de Agents e send mail tokens, converta as chamadas à API e os templates Mustache, troque o SMTP e migre os webhooks e as supressões.
Este guia mostra a correspondência entre os conceitos, as chamadas à API, os webhooks, as supressões e os templates do ZeptoMail e os equivalentes no Emailit. Em setembro de 2026, o ZeptoMail passou a se chamar Zoho CPaaS. Os tokens, os hosts e as configurações SMTP existentes continuam funcionando, então este guia usa os nomes do ZeptoMail que você vai encontrar no seu código. Leia antes Migrar para o Emailit para conhecer a ordem geral e saber como usar os dois provedores em paralelo.
Conceitos
| ZeptoMail (Zoho CPaaS) | Emailit |
|---|---|
| Account | Conta |
| Agents (antes chamados Mail Agents) | Workspaces, ou um workspace com vários domínios de envio |
| Send mail token de um Agent | Chave de API Sending Only, que pode ser restrita a um domínio |
| Tokens OAuth da Zoho para as APIs de gerenciamento | Chave de API Full Access. O mesmo tipo de chave envia e-mails e gerencia o seu workspace. |
| Domains associados aos Agents | Domínios de envio |
| Sandbox Agents | Os workspaces novos ficam no modo sandbox e só entregam para membros do workspace. Não há modo que aceite e-mails sem entregá-los. |
| Templates por Agent, com uma key e um alias | Templates por workspace, com alias e versões |
| Webhooks por Agent | Webhooks por workspace |
| Suppression list com entradas de e-mail e de domínio | Lista de supressão de endereços de e-mail |
| Processed emails e email logs | Email APIEmails e Email APILogs |
client_reference |
meta |
| File cache | Anexos por url |
O ZeptoMail só envia e-mails transacionais. No Emailit, o mesmo workspace também tem campanhas, listas de contatos e automações, se você quiser migrar as newsletters também.
Atualizar as chamadas à API
O POST /v1.1/email do ZeptoMail passa a ser POST /v2/emails. O esquema de autorização muda, e os endereços viram strings simples:
curl https://api.zeptomail.com/v1.1/email \
-H "Authorization: Zoho-enczapikey $ZEPTOMAIL_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"from": { "address": "hello@acme.com", "name": "Acme" },
"to": [{ "email_address": { "address": "ada@example.com" } }],
"subject": "Your receipt",
"textbody": "Thanks for your order.",
"htmlbody": "<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>"
}'| ZeptoMail | Emailit |
|---|---|
Authorization: Zoho-enczapikey <token> |
Authorization: Bearer secret_… |
Hosts regionais como api.zeptomail.eu ou cpaas.zoho.eu |
Um único host, api.emailit.com |
from: { address, name } |
from: "Name <email>" |
to[], cc[], bcc[] com email_address: { address, name } |
to, cc, bcc como string ou array de até 50 cada |
reply_to: [{ address, name }] |
reply_to |
subject |
subject |
htmlbody, textbody |
html, text |
mime_headers |
headers |
attachments[] com content, mime_type, name |
attachments[] com content, content_type, filename |
attachments[] com file_cache_key |
attachments[] com uma url que o Emailit baixa, ou o content em base64 |
inline_images[] com cid |
attachments[] com um content_id, referenciado como cid: no HTML |
client_reference |
meta, por exemplo meta: { "reference": "order-12345" }, devolvido nos eventos de webhook |
track_opens, track_clicks |
tracking: { "loads": true, "clicks": true } |
POST /v1.1/email/template com template_key ou template_alias e merge_info |
O mesmo POST /v2/emails com template (um alias ou ID) e variables |
POST /v1.1/email/batch e /email/template/batch |
Não disponível. Envie uma requisição por destinatário, cada uma com as suas variables. |
Resposta com request_id, e um email_reference por e-mail nos webhooks e nos logs |
200 com id (em_…), status: "accepted" e, para vários destinatários, ids, com um ID para cada um |
O Emailit também oferece agendamento com scheduled_at e novas tentativas seguras com um cabeçalho Idempotency-Key, o que o ZeptoMail não oferece no envio. Consulte Enviar um e-mail.
Mudar as configurações SMTP
| Configuração | ZeptoMail | Emailit |
|---|---|---|
| Host | smtp.zeptomail.com, ou um host regional |
smtp.emailit.com |
| Porta | 587 (STARTTLS), 465 (TLS) |
587, 2587, 2525 ou 25 (STARTTLS), 465 (TLS) |
| Usuário | emailapikey |
emailit |
| Senha | O send mail token do Agent, sem Zoho-enczapikey |
A sua chave de API do Emailit |
O Emailit não lê cabeçalhos X-TM-*, como X-TM-CLIENT-REF, X-TM-OPEN-TRACK, X-TM-CLICK-TRACK ou X-TM-FILE-KEY. Remova-os. 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 ZeptoMail | Evento do Emailit |
|---|---|
| Delivered | email.delivered |
Soft bounce (softbounce) |
email.attempted enquanto o Emailit faz novas tentativas, e depois email.bounced se todas as novas tentativas falharem |
Hard bounce (hardbounce) |
email.bounced |
Open (email_open), apenas a primeira abertura |
email.loaded, enviado a cada carregamento |
Click (email_link_click) |
email.clicked, enviado a cada clique |
Feedback loop (fbl_complaint) |
email.complained |
O Emailit também envia eventos para os quais o ZeptoMail não tem webhook, como 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 ZeptoMail envia
event_namee uma listaevent_message, com o e-mail ememail_infoe os detalhes emevent_data. O Emailit envia um array JSON de até 100 eventos, cada um com o nome emtypee o e-mail emdata.object. - Use
data.object.id, o IDem_da resposta do envio, em vez deemail_referenceourequest_id. Cada e-mail do Emailit tem um único destinatário,data.object.to, então você não precisa debounced_recipient. Os seus valores demetaficam 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 ZeptoMail assina com HMAC-SHA256 em um cabeçalho
producer-signatureque contémtse umsem base64. O Emailit enviaX-Emailit-Timestamp, em segundos, eX-Emailit-Signature, o HMAC-SHA256 em hexadecimal de<timestamp>.<raw body>, com o seu segredowhsec_como chave. 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 sua lista de supressão. A exportação pelo painel cobre os últimos 60 dias, com até 5.000 entradas por arquivo, então use a API de supressões (
GET /v1.1/suppressions/email) para as entradas mais antigas. -
Monte um único CSV com as colunas
email,type,reason:email,type,reason old-address@example.com,recipient,zeptomail hard bounce blocked@example.com,recipient,zeptomail suppressionUse o tipo
recipientpara os endereços com a açãosuppressoureject. Ele bloqueia envios pela API, por SMTP e de campanhas. As entradas comsuppress_trackingnão têm equivalente, então deixe-as de fora. -
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.
O Emailit suprime endereços exatos, então entradas de domínio como example.com não podem ser importadas. Consulte Gerenciar supressões.
Migrar os templates
Copie o HTML de cada template no editor do ZeptoMail ou obtenha-o pela API de templates, que o retorna em htmlbody. Importe-o em Email MarketingTemplates ou crie-o com a API de templates e use o alias do template no ZeptoMail como alias no Emailit, se ele se encaixar no formato de alias: letras minúsculas, números, - e _.
Os templates do ZeptoMail usam Mustache. O Temple cobre as partes mais comuns:
| ZeptoMail (Mustache) | Emailit (Temple) |
|---|---|
{{name}}, {{order.total}} |
Igual |
{{{html_block}}} |
{{html_block}}. O Temple nunca escapa HTML, então escape você mesmo o que vier dos usuários. |
{{#plan}}…{{/plan}} |
{{#if plan}}…{{/if}} |
{{^plan}}…{{/plan}} |
{{#if plan}}{{else}}…{{/if}} |
{{#items}}…{{/items}} sobre uma lista |
Não suportado. Renderize a lista no seu código e passe-a como uma única variável. |
| Sem valor padrão embutido | {{name|"there"}} adiciona um valor alternativo |
merge_info |
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 ZeptoMail, com o CNAME de bounce nem com o CNAME de rastreamento dele. Mantenha o seu registro DMARC. Consulte Registros DNS.
Depois da virada, remova os registros DKIM, de bounce e de rastreamento do ZeptoMail e include:zeptomail.net, se você o adicionou ao seu registro SPF.
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ê