# Migra da ZeptoMail

> Passa da ZeptoMail (ora Zoho CPaaS) a Emailit. Fai corrispondere Agents e send mail token, converti le chiamate API e i template Mustache, cambia SMTP e sposta webhook e soppressioni.

Questa guida fa corrispondere concetti, chiamate API, webhook, soppressioni e template di ZeptoMail ai loro equivalenti in Emailit. A settembre 2026 ZeptoMail è stato rinominato Zoho CPaaS. Token, host e impostazioni SMTP esistenti continuano a funzionare, quindi questa guida usa i nomi di ZeptoMail che trovi nel tuo codice. Leggi prima [Passa a Emailit](/it/docs/migrate/) per l’ordine generale e per sapere come usare entrambi i provider in parallelo.

## Concetti

| ZeptoMail (Zoho CPaaS) | Emailit |
| --- | --- |
| Account | Account |
| Agents (in precedenza Mail Agents) | [Workspace](/it/docs/workspaces/), oppure un solo workspace con più domini di invio |
| Send mail token di un Agent | [Chiave API](/it/docs/developers/api-keys/) **Sending Only**, facoltativamente limitata a un dominio |
| Token OAuth di Zoho per le API di gestione | Chiave API **Full Access**. Lo stesso tipo di chiave invia le email e gestisce il workspace. |
| Domini associati agli Agents | [Domini di invio](/it/docs/domains/) |
| Sandbox Agents | I nuovi workspace sono in [modalità sandbox](/it/docs/workspaces/production-access/) e consegnano solo ai membri del workspace. Non esiste una modalità che accetta le email senza consegnarle. |
| Template per Agent, con una chiave e un alias | [Template](/it/docs/templates/) per workspace, con un alias e versioni |
| Webhook per Agent | [Webhook](/it/docs/webhooks/) per workspace |
| Suppression list con voci di email e di dominio | [Lista di soppressione](/it/docs/suppressions/) di indirizzi email |
| Processed emails ed email logs | **Email API → Emails** e **Email API → Logs** |
| `client_reference` | `meta` |
| File cache | Allegati tramite `url` |

ZeptoMail invia solo email transazionali. In Emailit, lo stesso workspace ha anche [campagne](/it/docs/campaigns/), [liste](/it/docs/audiences/) e [automazioni](/it/docs/automations/), se vuoi spostare anche le newsletter.

## Aggiorna le chiamate API

`POST /v1.1/email` di ZeptoMail diventa `POST /v2/emails`. Cambia lo schema di autorizzazione, e gli indirizzi diventano semplici stringhe:

```bash title="Prima: 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="Dopo: 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_…` |
| Host regionali come `api.zeptomail.eu` o `cpaas.zoho.eu` | Un solo host, `api.emailit.com` |
| `from: { address, name }` | `from: "Name "` |
| `to[]`, `cc[]`, `bcc[]` con `email_address: { address, name }` | `to`, `cc`, `bcc` come stringa o array di massimo 50 ciascuno |
| `reply_to: [{ address, name }]` | `reply_to` |
| `subject` | `subject` |
| `htmlbody`, `textbody` | `html`, `text` |
| `mime_headers` | `headers` |
| `attachments[]` con `content`, `mime_type`, `name` | `attachments[]` con `content`, `content_type`, `filename` |
| `attachments[]` con `file_cache_key` | `attachments[]` con un `url` che Emailit scarica, oppure il `content` in base64 |
| `inline_images[]` con `cid` | `attachments[]` con un `content_id`, richiamato come `cid:` nell’HTML |
| `client_reference` | `meta`, ad esempio `meta: { "reference": "order-12345" }`, restituito negli eventi webhook |
| `track_opens`, `track_clicks` | `tracking: { "loads": true, "clicks": true }` |
| `POST /v1.1/email/template` con `template_key` o `template_alias` e `merge_info` | Lo stesso `POST /v2/emails` con `template` (un alias o un ID) e `variables` |
| `POST /v1.1/email/batch` e `/email/template/batch` | Non disponibile. Invia una richiesta per destinatario con le sue `variables`. |
| Risposta con `request_id`, e un `email_reference` per ogni email nei webhook e nei log | `200` con `id` (`em_…`), `status: "accepted"` e, con più destinatari, `ids` con un ID per ciascuno |

Emailit supporta anche la programmazione con `scheduled_at` e i nuovi tentativi sicuri con un header `Idempotency-Key`, che ZeptoMail non offre per l’invio. Vedi [Invia un’email](/it/docs/email-api/send-email/).

## Cambia le impostazioni SMTP

| Impostazione | ZeptoMail | Emailit |
| --- | --- | --- |
| Host | `smtp.zeptomail.com`, oppure un host regionale | `smtp.emailit.com` |
| Porta | `587` (STARTTLS), `465` (TLS) | `587`, `2587`, `2525` o `25` (STARTTLS), `465` (TLS) |
| Nome utente | `emailapikey` | `emailit` |
| Password | Il send mail token dell’Agent, senza `Zoho-enczapikey` | La tua chiave API di Emailit |

Emailit non legge gli header `X-TM-*` come `X-TM-CLIENT-REF`, `X-TM-OPEN-TRACK`, `X-TM-CLICK-TRACK` o `X-TM-FILE-KEY`. Rimuovili. Imposta il tracciamento sul dominio e usa l’API quando ti servono i metadati. Vedi [Impostazioni SMTP](/it/docs/smtp/settings/).

## Fai corrispondere gli eventi webhook

| Evento ZeptoMail | Evento Emailit |
| --- | --- |
| Delivered | `email.delivered` |
| Soft bounce (`softbounce`) | `email.attempted` mentre Emailit ritenta, poi `email.bounced` se tutti i nuovi tentativi non riescono |
| Hard bounce (`hardbounce`) | `email.bounced` |
| Open (`email_open`), solo la prima apertura | `email.loaded`, inviato per ogni caricamento |
| Click (`email_link_click`) | `email.clicked`, inviato per ogni clic |
| Feedback loop (`fbl_complaint`) | `email.complained` |

Emailit invia anche eventi per cui ZeptoMail non ha un webhook, come `email.accepted` quando l’API accetta un’email e `email.suppressed` quando una soppressione `recipient` blocca un indirizzo. Vedi [Tipi di evento](/it/docs/webhooks/event-types/).

Cambia il formato della richiesta:

- ZeptoMail invia `event_name` e un elenco `event_message`, con l’email in `email_info` e i dettagli in `event_data`. Emailit invia un array JSON di massimo 100 eventi, ciascuno con il nome in `type` e l’email in `data.object`.
- Usa `data.object.id`, l’ID `em_` della risposta all’invio, al posto di `email_reference` o `request_id`. Ogni email di Emailit ha un solo destinatario, `data.object.to`, quindi non ti serve `bounced_recipient`. I tuoi valori `meta` sono in `data.object.meta`.
- Per `email.loaded` ed `email.clicked`, `data.object` è il caricamento o il clic. Usa `data.object.email_id` per l’ID dell’email, e `data.object.email.rcpt_to` e `data.object.email.meta` per il destinatario e i tuoi valori `meta`.
- ZeptoMail firma con HMAC-SHA256 in un header `producer-signature` che contiene `ts` e un `s` in base64. Emailit invia `X-Emailit-Timestamp`, in secondi, e `X-Emailit-Signature`, l’HMAC-SHA256 in esadecimale di `<timestamp>.<raw body>` calcolato con il tuo secret `whsec_`. Vedi [Verifica le firme dei webhook](/it/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);
}
```

## Sposta le soppressioni

1. Esporta la lista di soppressione. L’esportazione dal pannello di ZeptoMail copre gli ultimi 60 giorni, con un massimo di 5000 voci per file, quindi usa l’API delle soppressioni (`GET /v1.1/suppressions/email`) per le voci più vecchie.

2. Crea un unico CSV con le colonne `email,type,reason`:

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

   Usa il tipo `recipient` per gli indirizzi con l’azione `suppress` o `reject`. Blocca gli invii via API, SMTP e campagne. Le voci con `suppress_tracking` non hanno un equivalente, quindi escludile.

3. In **Email API → Suppressions**, seleziona **Import** e carica il file. Ogni file può avere fino a 10.000 righe e pesare al massimo 8 MB. I duplicati vengono saltati.

Emailit sopprime indirizzi esatti, quindi le voci di dominio come `example.com` non si possono importare. Vedi [Gestisci le soppressioni](/it/docs/suppressions/manage/).

## Sposta i template

Copia l’HTML di ogni template dall’editor di ZeptoMail, oppure recuperalo dall’API dei template, che lo restituisce in `htmlbody`. Importalo in **Email Marketing → Templates** o crealo con l’[API dei template](/it/docs/api-reference/templates/create/), e usa l’alias del template di ZeptoMail come alias in Emailit, se rispetta il formato degli alias: lettere minuscole, numeri, `-` e `_`.

I template di ZeptoMail usano Mustache. Temple copre le parti più comuni:

| ZeptoMail (Mustache) | Emailit (Temple) |
| --- | --- |
| `{{name}}`, `{{order.total}}` | Uguale |
| `{{{html_block}}}` | `{{html_block}}`. Temple non applica mai l’escape all’HTML, quindi esegui tu l’escape dell’input degli utenti. |
| `{{#plan}}…{{/plan}}` | `{{#if plan}}…{{/if}}` |
| `{{^plan}}…{{/plan}}` | `{{#if plan}}{{else}}…{{/if}}` |
| `{{#items}}…{{/items}}` su un elenco | Non supportato. Genera l’elenco nel tuo codice e passalo come un’unica variabile. |
| Nessun valore predefinito integrato | `{{name\|"there"}}` aggiunge un valore di riserva |
| `merge_info` | `variables` |

Vedi [Temple](/it/docs/templates/temple/) e [Importa ed esporta i template](/it/docs/templates/import-export/).

## Cambia i DNS

Aggiungi il dominio in **Email API → Domains** e pubblica i record di Emailit. Usano nomi propri (`emailit._domainkey`, `emailit.<domain>` e, facoltativamente, `go` e `inbound`), quindi non entrano in conflitto con il record DKIM di ZeptoMail, con il suo CNAME di bounce né con il suo CNAME di tracciamento. Mantieni il record DMARC. Vedi [Record DNS](/it/docs/domains/dns-records/).

Dopo il passaggio, rimuovi i record DKIM, di bounce e di tracciamento di ZeptoMail, e `include:zeptomail.net` se l’hai aggiunto al record SPF.

## Passaggi successivi

- [Checklist per andare in produzione](/it/docs/get-started/go-live/)
- [Configura un webhook](/it/docs/webhooks/set-up/)
- [Migrazione prioritaria](/it/docs/programs/priority-migration/): lascia che i tecnici di Emailit facciano la migrazione insieme a te

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