Guida
Migra da Mandrill
Passa da Mandrill (Mailchimp Transactional) a Emailit. Fai corrispondere chiavi API e subaccount, converti le chiamate messages/send, cambia SMTP e header X-MC, verifica i webhook e sposta i rejects.
Questa guida fa corrispondere concetti, chiamate API, webhook, rejection denylist e template di Mandrill (Mailchimp Transactional Email) ai loro equivalenti in Emailit. Leggi prima Passa a Emailit per l’ordine generale e per sapere come usare entrambi i provider in parallelo. Se invii anche campagne da Mailchimp, vedi Migra da Mailchimp.
Concetti
| Mandrill | Emailit |
|---|---|
| Un piano Mailchimp Standard o Premium con blocchi di email transazionali | Un account Emailit. Non ti serve un piano di marketing per inviare email transazionali. |
| Subaccounts | Workspace, ognuno con i propri domini, chiavi, limiti e crediti |
| API keys | Chiavi API: Full Access, oppure Sending Only facoltativamente limitata a un dominio |
| Test API keys | Nessuna modalità di test. I nuovi workspace sono in modalità sandbox e possono inviare solo ai membri del workspace. |
| Sending domains e verifica DKIM/SPF | Domini di invio |
| Tracking domains | Sottodominio di tracciamento, come go.acme.com |
Templates con regioni mc:edit |
Template con un alias e versioni, elaborati con Temple |
| Webhooks | Webhook |
| Inbound domains e routes | Email in entrata |
| Rejection denylist | Soppressioni |
| Rejection allowlist | Non disponibile |
| Merge languages: Mailchimp e Handlebars | Temple |
| Tags e metadata | meta |
| Outbound activity | Email APIEmails e Email APILogs |
| Dedicated IPs e IP pools | IP dedicati su richiesta |
Aggiorna le chiamate API
POST /messages/send di Mandrill riceve la chiave API nel corpo JSON e annida l’email in message. POST /v2/emails di Emailit accetta un bearer token e un corpo piatto:
curl https://mandrillapp.com/api/1.0/messages/send \
-H "Content-Type: application/json" \
-d '{
"key": "'"$MANDRILL_API_KEY"'",
"message": {
"from_email": "hello@acme.com",
"from_name": "Acme",
"to": [{ "email": "ada@example.com", "type": "to" }],
"subject": "Your receipt",
"text": "Thanks for your order.",
"html": "<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>"
}'| Mandrill | Emailit |
|---|---|
key nel corpo della richiesta |
Header Authorization: Bearer secret_… |
message.from_email e from_name |
from: "Name <email>" |
message.to[] con type to, cc o bcc |
to, cc, bcc, fino a 50 ciascuno |
message.headers["Reply-To"] |
reply_to |
message.subject, html, text |
subject, html, text |
message.headers |
headers |
message.attachments[] con type, name, content |
attachments[] con content_type, filename, content |
message.images[] per le immagini inline |
attachments[] con un content_id, richiamato come cid: nell’HTML |
message.metadata, message.tags |
meta, un oggetto di valori stringa, restituito negli eventi webhook |
message.track_opens, track_clicks |
tracking: { "loads": true, "clicks": true } |
message.global_merge_vars |
variables |
message.merge_vars (per destinatario) |
Una richiesta per destinatario, ciascuna con le sue variables |
message.subaccount |
Usa una chiave API del workspace corrispondente |
send_at |
scheduled_at (ISO 8601 o inglese semplice) |
async |
Non serve. Emailit mette in coda ogni email per la consegna e risponde senza attenderla. |
POST /messages/send-template con template_name |
Lo stesso POST /v2/emails con template (un alias o un ID) e variables |
Risposta: un array con email, status e _id per ogni destinatario |
200 con id (em_…), status: "accepted" e, con più destinatari, ids con un ID per ciascuno |
Mandrill segnala i problemi per destinatario nella risposta, con stati come rejected o invalid. Emailit convalida l’intera richiesta e restituisce un errore HTTP per un input non valido. I destinatari con una soppressione recipient vengono accettati e poi ricevono lo stato suppressed. Aggiungi un header Idempotency-Key così i nuovi tentativi sono sicuri. Vedi Invia un’email.
Cambia le impostazioni SMTP
| Impostazione | Mandrill | Emailit |
|---|---|---|
| Host | smtp.mandrillapp.com |
smtp.emailit.com |
| Porta | 587, 2525 o 25 (STARTTLS), 465 (TLS) |
587, 2587, 2525 o 25 (STARTTLS), 465 (TLS) |
| Nome utente | Qualsiasi valore | emailit |
| Password | Una chiave API di Mandrill | La tua chiave API di Emailit |
Emailit non legge gli header X-MC-* come X-MC-Template, X-MC-MergeVars, X-MC-Tags, X-MC-Metadata o X-MC-Track. Rimuovili. Imposta il tracciamento sul dominio e usa l’API quando ti servono template o metadati. Vedi Impostazioni SMTP.
Fai corrispondere gli eventi webhook
| Evento Mandrill | Evento Emailit |
|---|---|
send |
email.accepted (solo API) |
delivered |
email.delivered |
deferral |
email.attempted |
hard_bounce |
email.bounced |
soft_bounce |
email.attempted mentre Emailit ritenta, poi email.bounced se tutti i nuovi tentativi non riescono |
open |
email.loaded |
click |
email.clicked |
spam |
email.complained |
unsub |
email.unsubscribed, solo per le email delle campagne |
reject |
email.suppressed quando l’indirizzo ha una soppressione recipient. Gli altri motivi di rifiuto, come unsigned, in Emailit sono errori dell’API. |
| Eventi di sincronizzazione della rejection denylist | suppression.created, suppression.deleted, per le soppressioni che aggiungi o rimuovi |
inbound |
email.received, poi recupera il contenuto con GET /emails/{id} |
Cambia il formato della richiesta:
- Mandrill invia un campo di modulo,
mandrill_events, che contiene un array JSON di massimo 1000 eventi. Emailit invia l’array JSON come corpo della richiesta, con un massimo di 100 eventi. - Il nome dell’evento è in
type, e l’email è indata.object. Usadata.object.id, l’IDem_della risposta all’invio, al posto di_id, edata.object.toal posto dimsg.email. 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. - Mandrill firma l’URL e i campi del modulo con HMAC-SHA1, codificato in base64, in
X-Mandrill-Signature. Emailit firma<timestamp>.<raw body>con HMAC-SHA256: verificaX-Emailit-Signaturerispetto aX-Emailit-Timestampe al 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 l’intera rejection denylist con Export Full Denylist nella pagina Rejection Denylist di Mandrill, oppure con la chiamata API
/exports/rejects./rejects/listrestituisce al massimo 1000 voci, quindi non usarla per questo. L’esportazione è un file ZIP conrejects.csve copre tutti i subaccount. -
Crea un unico CSV con le colonne
email,type,reason. Salta le voci già scadute e usa la colonnareasonper scegliere il tipo:Motivo in Mandrill Tipo in Emailit hard-bounce,spam,customrecipientunsubunsubscribe, che ferma le campagne ma lascia passare le email transazionali. Usarecipientper bloccare tutte le email, come faceva Mandrill.soft-bounceEscludile. Scadono dopo un giorno. email,type,reason old-address@example.com,recipient,mandrill hard-bounce angry@example.com,recipient,mandrill spamIl tipo
recipientblocca gli invii via API, SMTP e campagne. Se usavi i subaccount, dividi il file in base alla colonna del subaccount e importa ogni parte nel workspace corrispondente. -
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.
La rejection allowlist di Mandrill non ha un equivalente. Vedi Gestisci le soppressioni.
Sposta i template
Recupera il codice dei template da Mandrill: una sola chiamata /templates/list restituisce tutti i template con il loro slug e l’HTML pubblicato in publish_code. Poi importa ciascuno in Email MarketingTemplates o crealo con l’API dei template. Usa lo slug di Mandrill come alias, se rispetta il formato degli alias: lettere minuscole, numeri, - e _.
I template che usavano regioni mc:edit compilate da template_content richiedono che quelle regioni diventino variabili. I nomi delle merge variable di Mandrill non distinguono tra maiuscole e minuscole, quelli di Temple sì: {{FNAME}} corrisponde solo a una variabile chiamata FNAME. Converti i merge tag in Temple:
| Mandrill | Emailit (Temple) |
|---|---|
*|FNAME|* (merge language Mailchimp) |
{{FNAME}}, oppure rinominalo in {{first_name}} |
{{fname}} (merge language Handlebars) |
{{fname}} |
*|IF:FNAME|*…*|ELSE:|*…*|END:IF|* |
{{#if FNAME}}…{{else}}…{{/if}} |
*|IF:PLAN=pro|*, o un confronto dentro un {{#if}} di Handlebars |
Non supportato. Passa un booleano come is_pro e usa {{#if is_pro}}. |
*|DATE:d/m/y|*, *|CURRENT_YEAR|*, helper come {{upper name}} |
Non supportato. Formatta il valore nel tuo codice e passalo. |
*|UNSUB:https://…|*, {{unsub "…"}} |
Un tuo link di disiscrizione. Vedi Disiscrizioni. |
{{#if plan}}…{{else}}…{{/if}} |
Uguale |
{{#each items}}…{{/each}} |
Non supportato. Genera l’elenco nel tuo codice e passalo come un’unica variabile. |
<div mc:edit="body">…</div> con template_content |
{{body}}, passato in variables |
global_merge_vars |
variables |
Temple non applica mai l’escape all’HTML, quindi esegui l’escape dell’input degli utenti prima di passarlo. Un valore mancante diventa una stringa vuota, a meno che tu non aggiunga un valore predefinito, come {{name|"there"}}. Vedi Temple.
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 i CNAME mte1._domainkey e mte2._domainkey di Mandrill né con il suo record TXT mandrill_verify. Mantieni il record DMARC. Vedi Record DNS.
Dopo il passaggio, rimuovi i record DKIM e di verifica di Mandrill, gli eventuali CNAME personalizzati di tracciamento o di return path, e include:spf.mandrillapp.com se il record SPF lo contiene. Se ricevi posta con le inbound routes di Mandrill, spostala prima su un sottodominio di ricezione di Emailit.
Passaggi successivi
- Checklist per andare in produzione
- Configura un webhook
- Migrazione prioritaria: lascia che i tecnici di Emailit facciano la migrazione insieme a te