Guida
Migra da Mailtrap
Passa da Mailtrap Email Sending a Emailit. Fai corrispondere stream, token e sub-account, converti le chiamate API e i template Handlebars, cambia le impostazioni SMTP e sposta webhook, soppressioni e contatti.
Questa guida fa corrispondere concetti, chiamate API, webhook, soppressioni, template e contatti di Mailtrap Email Sending ai loro equivalenti in Emailit. Leggi prima Passa a Emailit per l’ordine generale e per sapere come usare entrambi i provider in parallelo.
Concetti
| Mailtrap | Emailit |
|---|---|
| Organizzazione e sub-account | Account e workspace. Ogni workspace ha i propri domini, chiavi, membri e crediti. |
| Sending domains | Domini di invio |
| Transactional stream | L’API email e l’SMTP relay |
| Bulk stream | Campagne, oppure l’API con i tuoi header List-Unsubscribe |
| API token con permessi per risorsa | Chiavi API: Full Access, oppure Sending Only facoltativamente limitata a un dominio |
| Demo domain | I nuovi workspace sono in modalità sandbox e possono inviare ai membri del workspace dal tuo dominio verificato. |
| Email Sandbox (test) | Non disponibile. Mantieni la sandbox di Mailtrap per i test, oppure invia ai membri del workspace durante lo sviluppo. |
| Templates | Template con un alias e versioni, elaborati con Temple |
| Webhook per stream | Webhook per workspace |
| Suppressions per dominio e per stream | Una lista di soppressione per workspace |
| Email logs | Email APIEmails e Email APILogs |
category e custom_variables |
meta |
| Email Marketing: contatti, liste, campagne, automazioni | Contatti, liste, campagne e automazioni (beta) |
| Inbound email | Email in entrata |
Per tenere separate la reputazione transazionale e quella di marketing, come fanno i due stream di Mailtrap, invia da domini o sottodomini diversi, come mail.acme.com per le ricevute e news.acme.com per le newsletter.
Aggiorna le chiamate API
POST /api/send di Mailtrap diventa POST /v2/emails. Entrambi accettano un bearer token e JSON, ma in Emailit gli indirizzi sono semplici stringhe anziché oggetti:
curl https://send.api.mailtrap.io/api/send \
-H "Authorization: Bearer $MAILTRAP_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"from": { "email": "hello@acme.com", "name": "Acme" },
"to": [{ "email": "ada@example.com" }],
"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>"
}'| Mailtrap | Emailit |
|---|---|
Authorization: Bearer <token> o Api-Token: <token> |
Authorization: Bearer secret_… |
send.api.mailtrap.io e bulk.api.mailtrap.io |
Un solo host, api.emailit.com |
from: { email, name } |
from: "Name <email>" |
to[], cc[], bcc[] con email e name |
to, cc, bcc come stringa o array di massimo 50 ciascuno |
reply_to: { email, name } |
reply_to |
subject, text, html, headers |
Uguali |
attachments[] con content, filename, type, disposition e content_id |
attachments[] con content, filename, content_type e content_id, oppure un url al posto di content |
category |
meta, ad esempio meta: { "category": "password-reset" } |
custom_variables |
meta, restituito negli eventi webhook |
template_uuid e template_variables |
template (un alias o un ID) e variables |
| Tracciamento impostato per dominio | Tracciamento impostato per dominio, oppure per singola email con tracking: { "loads": true, "clicks": true } |
POST /api/batch (fino a 500 messaggi) |
Non disponibile. Invia una richiesta per messaggio. |
Risposta con message_ids, uno per destinatario |
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 l’API di invio di Mailtrap non offre. Vedi Invia un’email.
Cambia le impostazioni SMTP
| Impostazione | Mailtrap | Emailit |
|---|---|---|
| Host | live.smtp.mailtrap.io, oppure bulk.smtp.mailtrap.io per il bulk stream |
smtp.emailit.com |
| Porta | 587, 2525 o 25 (STARTTLS), 465 (TLS) |
587, 2587, 2525 o 25 (STARTTLS), 465 (TLS) |
| Nome utente | api |
emailit |
| Password | Il tuo API token di Mailtrap | La tua chiave API di Emailit |
Emailit non legge gli header X-MT-Category e X-MT-Custom-Variables. Rimuovili e usa l’API quando ti servono i metadati. Vedi Impostazioni SMTP.
Fai corrispondere gli eventi webhook
| Evento Mailtrap | Evento Emailit |
|---|---|
delivery |
email.delivered |
soft bounce |
email.attempted mentre Emailit ritenta, poi email.bounced se tutti i nuovi tentativi non riescono |
bounce |
email.bounced |
reject |
email.suppressed quando l’indirizzo ha una soppressione recipient |
suspension |
email.held |
spam |
email.complained |
open |
email.loaded |
click |
email.clicked |
unsubscribe |
email.unsubscribed, solo per le email delle campagne |
inbound.message_received |
email.received, poi recupera il contenuto con GET /emails/{id} |
Emailit invia anche email.accepted quando l’API accetta un’email. Vedi Tipi di evento.
Cambia il formato della richiesta:
- Mailtrap invia un elenco
eventsdi massimo 500 eventi, oppure JSON Lines. Emailit invia come corpo della richiesta un array JSON di massimo 100 eventi. - Il nome dell’evento è in
type, e l’email si trova indata.object. Usadata.object.id, l’IDem_della risposta all’invio, al posto dimessage_id, edata.object.toal posto diemail. I tuoi valorimeta, che sostituisconocategoryecustom_variables, sono 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. - L’header
Mailtrap-Signaturedi Mailtrap è un HMAC-SHA256 del corpo grezzo. L’headerX-Emailit-Signaturedi Emailit è un HMAC-SHA256 di<timestamp>.<raw body>, calcolato con il tuo secretwhsec_, quindi leggi ancheX-Emailit-Timestamp. 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 le soppressioni da Suppressions in Mailtrap, oppure scorri le pagine di
GET https://mailtrap.io/api/suppressions, che restituisce fino a 1000 voci per chiamata. -
Crea un unico CSV con le colonne
email,type,reason:Tipo in Mailtrap Tipo in Emailit hard bounce,spam complaint,manual importrecipient, che blocca gli invii via API, SMTP e campagneunsubscriptionunsubscribe, che ferma le campagne ma lascia passare le email transazionali. Usarecipientper le disiscrizioni dal transactional stream.email,type,reason old-address@example.com,recipient,mailtrap hard bounce left@example.com,unsubscribe,mailtrap unsubscription -
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, quindi gli indirizzi soppressi per più domini o stream di Mailtrap vengono aggiunti una sola volta.
Vedi Gestisci le soppressioni.
Sposta i contatti
Se usi Mailtrap Email Marketing, esporta i contatti da Contacts con More Actions > Export, oppure con POST https://mailtrap.io/api/contacts/exports filtrato su subscription_status e list_id. Prima crea in Emailit i campi personalizzati e le liste corrispondenti.
Importa solo i contatti iscritti, una lista alla volta, in Email MarketingContacts con Import. L’importazione aggiunge come iscritte tutte le persone nel file, quindi aggiungi invece i contatti disiscritti al file delle soppressioni con il tipo unsubscribe. Dividi i file in parti di massimo 2500 righe. Vedi Importa ed esporta i contatti.
Sposta i template
Recupera l’HTML dei template con GET https://mailtrap.io/api/email_templates, che restituisce body_html, body_text e subject di ogni template. Importali uno per uno in Email MarketingTemplates o creali con l’API dei template, e assegna a ciascuno un alias, come receipt.
I template di Mailtrap usano Handlebars. Temple copre le parti più comuni:
| Mailtrap (Handlebars) | Emailit (Temple) |
|---|---|
{{name}}, {{user.name}} |
Uguale |
{{{html_block}}} |
{{html_block}}. Temple non applica mai l’escape all’HTML, quindi esegui tu l’escape dell’input degli utenti. |
{{#if plan}}…{{else}}…{{/if}} |
Uguale |
{{#unless plan}}…{{/unless}} |
{{#if plan}}{{else}}…{{/if}} |
{{#if name}}{{name}}{{else}}Customer{{/if}} |
{{name|"Customer"}} |
{{#each items}}…{{/each}}, {{#with}} |
Non supportati. Genera l’elenco nel tuo codice e passalo come un’unica variabile. |
template_variables |
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 i record DKIM rwmt1._domainkey e rwmt2._domainkey di Mailtrap, con il suo CNAME di verifica né con il suo CNAME di tracciamento mt-link. Mantieni il record DMARC. Vedi Record DNS.
Dopo il passaggio, rimuovi i record DKIM, di verifica e di tracciamento di Mailtrap, e togli include:_spf.mailtrap.io dal record SPF, se lo contiene ancora. Le email in entrata di Mailtrap arrivano tramite il record MX del dominio principale, quelle di Emailit su un sottodominio come inbound.acme.com, quindi sposta la posta in entrata e aggiorna gli indirizzi di ricezione prima di cambiare il record MX. Vedi Configura le email in entrata.
Passaggi successivi
- Checklist per andare in produzione
- Configura un webhook
- Migrazione prioritaria: lascia che i tecnici di Emailit facciano la migrazione insieme a te