# Migrate from ZeptoMail

> Move from ZeptoMail (now Zoho CPaaS) to Emailit. Map Agents and send mail tokens, convert API calls and Mustache templates, swap SMTP, and move webhooks and suppressions.

This guide maps ZeptoMail concepts, API calls, webhooks, suppressions and templates to their Emailit equivalents. In September 2026 ZeptoMail was renamed Zoho CPaaS. Existing tokens, hosts and SMTP settings keep working, so this guide uses the ZeptoMail names you'll find in your code. Read [Migrate to Emailit](/docs/migrate/) first for the overall order and how to run both providers in parallel.

## Concepts

| ZeptoMail (Zoho CPaaS) | Emailit |
| --- | --- |
| Account | Account |
| Agents (formerly Mail Agents) | [Workspaces](/docs/workspaces/), or one workspace with several sending domains |
| Send mail token of an Agent | **Sending Only** [API key](/docs/developers/api-keys/), optionally restricted to one domain |
| Zoho OAuth tokens for the management APIs | **Full Access** API key. The same kind of key sends email and manages your workspace. |
| Domains associated with Agents | [Sending domains](/docs/domains/) |
| Sandbox Agents | New workspaces are in [sandbox mode](/docs/workspaces/production-access/) and deliver only to workspace members. There's no mode that accepts email without delivering it. |
| Templates per Agent, with a key and an alias | [Templates](/docs/templates/) per workspace, with an alias and versions |
| Webhooks per Agent | [Webhooks](/docs/webhooks/) per workspace |
| Suppression list with email and domain entries | [Suppression list](/docs/suppressions/) of email addresses |
| Processed emails and email logs | **Email API → Emails** and **Email API → Logs** |
| `client_reference` | `meta` |
| File cache | Attachments by `url` |

ZeptoMail only sends transactional email. In Emailit, the same workspace also has [campaigns](/docs/campaigns/), [audiences](/docs/audiences/) and [automations](/docs/automations/), if you want to move newsletters too.

## Update your API calls

ZeptoMail's `POST /v1.1/email` becomes `POST /v2/emails`. The authorization scheme changes, and addresses become plain strings:

```bash title="Before: 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="After: 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_…` |
| Regional hosts such as `api.zeptomail.eu` or `cpaas.zoho.eu` | One host, `api.emailit.com` |
| `from: { address, name }` | `from: "Name "` |
| `to[]`, `cc[]`, `bcc[]` with `email_address: { address, name }` | `to`, `cc`, `bcc` as a string or an array of up to 50 each |
| `reply_to: [{ address, name }]` | `reply_to` |
| `subject` | `subject` |
| `htmlbody`, `textbody` | `html`, `text` |
| `mime_headers` | `headers` |
| `attachments[]` with `content`, `mime_type`, `name` | `attachments[]` with `content`, `content_type`, `filename` |
| `attachments[]` with `file_cache_key` | `attachments[]` with a `url` that Emailit downloads, or the base64 `content` |
| `inline_images[]` with `cid` | `attachments[]` with a `content_id`, referenced as `cid:` in the HTML |
| `client_reference` | `meta`, for example `meta: { "reference": "order-12345" }`, returned in webhook events |
| `track_opens`, `track_clicks` | `tracking: { "loads": true, "clicks": true }` |
| `POST /v1.1/email/template` with `template_key` or `template_alias` and `merge_info` | The same `POST /v2/emails` with `template` (an alias or ID) and `variables` |
| `POST /v1.1/email/batch` and `/email/template/batch` | Not available. Send one request per recipient with its own `variables`. |
| Response with `request_id`, and an `email_reference` per email in webhooks and logs | `200` with `id` (`em_…`), `status: "accepted"` and, for several recipients, `ids` with one ID each |

Emailit also supports scheduling with `scheduled_at` and safe retries with an `Idempotency-Key` header, which ZeptoMail doesn't offer on send. See [Send an email](/docs/email-api/send-email/).

## Switch SMTP settings

| Setting | ZeptoMail | Emailit |
| --- | --- | --- |
| Host | `smtp.zeptomail.com`, or a regional host | `smtp.emailit.com` |
| Port | `587` (STARTTLS), `465` (TLS) | `587`, `2587`, `2525` or `25` (STARTTLS), `465` (TLS) |
| Username | `emailapikey` | `emailit` |
| Password | The Agent's send mail token, without `Zoho-enczapikey` | Your Emailit API key |

Emailit doesn't read `X-TM-*` headers such as `X-TM-CLIENT-REF`, `X-TM-OPEN-TRACK`, `X-TM-CLICK-TRACK` or `X-TM-FILE-KEY`. Remove them. Set tracking on the domain, and use the API when you need metadata. See [SMTP settings](/docs/smtp/settings/).

## Map webhook events

| ZeptoMail event | Emailit event |
| --- | --- |
| Delivered | `email.delivered` |
| Soft bounce (`softbounce`) | `email.attempted` while Emailit retries, then `email.bounced` if every retry fails |
| Hard bounce (`hardbounce`) | `email.bounced` |
| Open (`email_open`), first open only | `email.loaded`, sent for every load |
| Click (`email_link_click`) | `email.clicked`, sent for every click |
| Feedback loop (`fbl_complaint`) | `email.complained` |

Emailit also sends events ZeptoMail has no webhook for, such as `email.accepted` when the API accepts an email and `email.suppressed` when a `recipient` suppression blocks an address. See [Event types](/docs/webhooks/event-types/).

The request format changes:

- ZeptoMail posts `event_name` and an `event_message` list, with the email in `email_info` and the details in `event_data`. Emailit posts a JSON array of up to 100 events, each with the name in `type` and the email in `data.object`.
- Use `data.object.id`, the `em_` ID from the send response, instead of `email_reference` or `request_id`. Each Emailit email has one recipient, `data.object.to`, so you don't need `bounced_recipient`. Your `meta` values are in `data.object.meta`.
- For `email.loaded` and `email.clicked`, `data.object` is the load or the click. Use `data.object.email_id` for the email's ID, and `data.object.email.rcpt_to` and `data.object.email.meta` for the recipient and your `meta` values.
- ZeptoMail signs with HMAC-SHA256 in a `producer-signature` header that holds `ts` and a base64 `s`. Emailit sends `X-Emailit-Timestamp`, in seconds, and `X-Emailit-Signature`, the hex HMAC-SHA256 of `<timestamp>.<raw body>` keyed with your `whsec_` secret. See [Request signature](/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);
}
```

## Move suppressions

1. Export your suppression list. The dashboard export covers the last 60 days with up to 5,000 entries per file, so use the suppressions API (`GET /v1.1/suppressions/email`) for older entries.

2. Build one CSV with the columns `email,type,reason`:

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

   Use the type `recipient` for addresses with the action `suppress` or `reject`. It blocks API, SMTP and campaign sends. Entries with `suppress_tracking` have no equivalent, so leave them out.

3. In **Email API → Suppressions**, select **Import** and upload the file. Each file can have up to 10,000 rows and can be at most 8 MB. Duplicates are skipped.

Emailit suppresses exact addresses, so domain entries such as `example.com` can't be imported. See [Manage suppressions](/docs/suppressions/manage/).

## Move templates

Copy each template's HTML from the ZeptoMail editor, or get it from the templates API, which returns it in `htmlbody`. Import it in **Email Marketing → Templates** or create it with the [Templates API](/docs/api-reference/templates/create/), and use the ZeptoMail template alias as the Emailit alias if it fits the alias format of lowercase letters, numbers, `-` and `_`.

ZeptoMail templates use Mustache. Temple covers the common parts:

| ZeptoMail (Mustache) | Emailit (Temple) |
| --- | --- |
| `{{name}}`, `{{order.total}}` | The same |
| `{{{html_block}}}` | `{{html_block}}`. Temple never escapes HTML, so escape user input yourself. |
| `{{#plan}}…{{/plan}}` | `{{#if plan}}…{{/if}}` |
| `{{^plan}}…{{/plan}}` | `{{#if plan}}{{else}}…{{/if}}` |
| `{{#items}}…{{/items}}` over a list | Not supported. Render the list in your code and pass it as one variable. |
| No built-in default | `{{name\|"there"}}` adds a fallback |
| `merge_info` | `variables` |

See [Temple](/docs/templates/temple/) and [Import and export templates](/docs/templates/import-export/).

## Change DNS

Add your domain in **Email API → Domains** and publish the Emailit records. They use their own names (`emailit._domainkey`, `emailit.<domain>`, and optionally `go` and `inbound`), so they don't conflict with ZeptoMail's DKIM record, its bounce CNAME or its tracking CNAME. Keep your DMARC record. See [DNS records](/docs/domains/dns-records/).

After the cutover, remove the ZeptoMail DKIM, bounce and tracking records, and `include:zeptomail.net` if you added it to your SPF record.

## Next steps

- [Go-live checklist](/docs/get-started/go-live/)
- [Set up webhooks](/docs/webhooks/set-up/)
- [Priority migration](/docs/programs/priority-migration/): let Emailit engineers do the move with you

---
Source: https://emailit.com/docs/migrate/zeptomail/
