# 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](/pt/docs/migrate/) 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](/pt/docs/workspaces/), ou um workspace com vários domínios de envio |
| Send mail token de um Agent | [Chave de API](/pt/docs/developers/api-keys/) **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](/pt/docs/domains/) |
| Sandbox Agents | Os workspaces novos ficam no [modo sandbox](/pt/docs/workspaces/production-access/) 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](/pt/docs/templates/) por workspace, com alias e versões |
| Webhooks por Agent | [Webhooks](/pt/docs/webhooks/) por workspace |
| Suppression list com entradas de e-mail e de domínio | [Lista de supressão](/pt/docs/suppressions/) de endereços de e-mail |
| Processed emails e email logs | **Email API → Emails** e **Email API → Logs** |
| `client_reference` | `meta` |
| File cache | Anexos por `url` |

O ZeptoMail só envia e-mails transacionais. No Emailit, o mesmo workspace também tem [campanhas](/pt/docs/campaigns/), [listas de contatos](/pt/docs/audiences/) e [automações](/pt/docs/automations/), 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:

```bash title="Antes: ZeptoMail"
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>"
  }'
```

```bash title="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>"
  }'
```

| 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 "` |
| `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](/pt/docs/email-api/send-email/).

## 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](/pt/docs/smtp/settings/).

## 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](/pt/docs/webhooks/event-types/).

O formato da requisição muda:

- O ZeptoMail envia `event_name` e uma lista `event_message`, com o e-mail em `email_info` e os detalhes em `event_data`. O Emailit envia um array JSON de até 100 eventos, cada um com o nome em `type` e o e-mail em `data.object`.
- Use `data.object.id`, o ID `em_` da resposta do envio, em vez de `email_reference` ou `request_id`. Cada e-mail do Emailit tem um único destinatário, `data.object.to`, então você não precisa de `bounced_recipient`. Os seus valores de `meta` 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 ZeptoMail assina com HMAC-SHA256 em um cabeçalho `producer-signature` que contém `ts` e um `s` em base64. O Emailit envia `X-Emailit-Timestamp`, em segundos, e `X-Emailit-Signature`, o HMAC-SHA256 em hexadecimal de `<timestamp>.<raw body>`, com o seu segredo `whsec_` como chave. Consulte [Assinatura das requisições](/pt/docs/webhooks/request-signature/).

```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 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.

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

```csv
email,type,reason
old-address@example.com,recipient,zeptomail hard bounce
blocked@example.com,recipient,zeptomail suppression
```

   Use o tipo `recipient` para os endereços com a ação `suppress` ou `reject`. Ele bloqueia envios pela API, por SMTP e de campanhas. As entradas com `suppress_tracking` não têm equivalente, então deixe-as de fora.

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. 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](/pt/docs/suppressions/manage/).

## 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 Marketing → Templates** ou crie-o com a [API de templates](/pt/docs/api-reference/templates/create/) 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](/pt/docs/templates/temple/) e [Importar e exportar templates](/pt/docs/templates/import-export/).

## 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 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](/pt/docs/domains/dns-records/).

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](/pt/docs/get-started/go-live/)
- [Configurar webhooks](/pt/docs/webhooks/set-up/)
- [Migração prioritária](/pt/docs/programs/priority-migration/): deixe os engenheiros do Emailit fazerem a migração com você

---
Fonte: https://emailit.com/pt/docs/migrate/zeptomail/
