Guida
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 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, oppure un solo workspace con più domini di invio |
| Send mail token di un Agent | Chiave API 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 |
| Sandbox Agents | I nuovi workspace sono in modalità sandbox 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 per workspace, con un alias e versioni |
| Webhook per Agent | Webhook per workspace |
| Suppression list con voci di email e di dominio | Lista di soppressione di indirizzi email |
| Processed emails ed email logs | Email APIEmails e Email APILogs |
client_reference |
meta |
| File cache | Allegati tramite url |
ZeptoMail invia solo email transazionali. In Emailit, lo stesso workspace ha anche campagne, liste e automazioni, 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:
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_… |
Host regionali come api.zeptomail.eu o cpaas.zoho.eu |
Un solo host, api.emailit.com |
from: { address, name } |
from: "Name <email>" |
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.
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.
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.
Cambia il formato della richiesta:
- ZeptoMail invia
event_namee un elencoevent_message, con l’email inemail_infoe i dettagli inevent_data. Emailit invia un array JSON di massimo 100 eventi, ciascuno con il nome intypee l’email indata.object. - Usa
data.object.id, l’IDem_della risposta all’invio, al posto diemail_referenceorequest_id. Ogni email di Emailit ha un solo destinatario,data.object.to, quindi non ti servebounced_recipient. I tuoi valorimetasono indata.object.meta. - Per
email.loadededemail.clicked,data.objectè il caricamento o il clic. Usadata.object.email_idper l’ID dell’email, edata.object.email.rcpt_toedata.object.email.metaper il destinatario e i tuoi valorimeta. - ZeptoMail firma con HMAC-SHA256 in un header
producer-signatureche contienetse unsin base64. Emailit inviaX-Emailit-Timestamp, in secondi, eX-Emailit-Signature, l’HMAC-SHA256 in esadecimale di<timestamp>.<raw body>calcolato con il tuo secretwhsec_. Vedi Verifica le firme dei webhook.
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
-
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. -
Crea un unico CSV con le colonne
email,type,reason:email,type,reason old-address@example.com,recipient,zeptomail hard bounce blocked@example.com,recipient,zeptomail suppressionUsa il tipo
recipientper gli indirizzi con l’azionesuppressoreject. Blocca gli invii via API, SMTP e campagne. Le voci consuppress_trackingnon hanno un equivalente, quindi escludile. -
In Email APISuppressions, 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.
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 MarketingTemplates o crealo con l’API dei template, 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 e Importa ed esporta i template.
Cambia i DNS
Aggiungi il dominio in Email APIDomains 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.
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
- Configura un webhook
- Migrazione prioritaria: lascia che i tecnici di Emailit facciano la migrazione insieme a te