Guida
Migra da MailerSend
Passa da MailerSend a Emailit. Fai corrispondere domini, token e utenti SMTP, converti chiamate API e personalizzazione, cambia le impostazioni SMTP e sposta webhook, soppressioni e template.
Questa guida fa corrispondere concetti, chiamate API, webhook, soppressioni e template di MailerSend 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
| MailerSend | Emailit |
|---|---|
| Account | Account e workspace. Ogni workspace ha i propri domini, chiavi, membri e crediti. |
| Domains | Domini di invio |
| Sender identities | Non disponibile. Ogni indirizzo From deve trovarsi su un dominio verificato. |
| API token con permessi | Chiavi API: Full Access, oppure Sending Only facoltativamente limitata a un dominio |
| Utenti SMTP | La tua chiave API, usata come password SMTP |
| Dominio di test e modalità sandbox | Nessun dominio di test condiviso. I nuovi workspace sono in modalità sandbox e possono inviare solo ai membri del workspace. |
| Templates | Template con un alias e versioni, elaborati con Temple |
| Webhook per dominio | Webhook per workspace |
| Inbound routes | Email in entrata, con il webhook email.received oppure l’automazione Forward received email |
| Suppressions per dominio: hard bounces, spam complaints, unsubscribes, blocklist | Una lista di soppressione per workspace |
| On hold list | Non serve. Emailit ritenta i soft bounce e segnala ogni tentativo come email.attempted. |
| Activity | Email APIEmails e Email APILogs |
| Tags | meta |
| Email verification | Verifica email |
| Dedicated IPs | IP dedicati su richiesta |
Aggiorna le chiamate API
POST /v1/email di MailerSend diventa POST /v2/emails. Entrambi accettano un bearer token e JSON, ma in Emailit gli indirizzi sono semplici stringhe anziché oggetti:
curl https://api.mailersend.com/v1/email \
-H "Authorization: Bearer $MAILERSEND_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>"
}'| MailerSend | Emailit |
|---|---|
Authorization: Bearer <token> |
Authorization: Bearer secret_… |
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 |
Uguali |
headers: [{ "name": "…", "value": "…" }] |
headers: { "Name": "Value" } |
list_unsubscribe |
headers con List-Unsubscribe e List-Unsubscribe-Post. Vedi Header e metadati. |
attachments[] con content, filename, disposition e id |
attachments[] con content, filename e content_type, oppure un url al posto di content. Usa content_id per le immagini inline. |
template_id |
template, l’ID o l’alias di un template |
personalization: [{ "email": "…", "data": { … } }] |
variables, con una richiesta per destinatario quando i valori sono diversi |
tags |
meta, restituito negli eventi webhook |
send_at (timestamp Unix o ISO 8601) |
scheduled_at (ISO 8601 o inglese semplice). Converti prima i timestamp Unix in ISO 8601. |
settings.track_opens, settings.track_clicks |
tracking: { "loads": true, "clicks": true } |
POST /v1/bulk-email |
Non disponibile. Invia una richiesta per messaggio. |
202 Accepted con un header x-message-id e un corpo vuoto |
200 con un corpo JSON: id (em_…), status: "accepted" e, con più destinatari, ids con un ID per ciascuno |
Ogni destinatario di una richiesta Emailit diventa un’email a sé, con il proprio ID. MailerSend risponde 202 anche quando tutti i destinatari sono soppressi, con un avviso nel corpo. Anche Emailit accetta i destinatari con una soppressione recipient e assegna a ciascuno lo stato suppressed. Aggiungi un header Idempotency-Key così i nuovi tentativi sono sicuri. Vedi Invia un’email.
Cambia le impostazioni SMTP
| Impostazione | MailerSend | Emailit |
|---|---|---|
| Host | smtp.mailersend.net |
smtp.emailit.com |
| Porta | 587 (STARTTLS) |
587, 2587, 2525 o 25 (STARTTLS), 465 (TLS) |
| Nome utente | Il nome utente generato per l’utente SMTP | emailit |
| Password | La password dell’utente SMTP | La tua chiave API di Emailit |
Emailit non legge l’header X-MailerSend-Tags. Rimuovilo. A differenza di MailerSend, Emailit consegna invariati gli altri header personalizzati. Vedi Impostazioni SMTP.
Fai corrispondere gli eventi webhook
| Evento MailerSend | Evento Emailit |
|---|---|
activity.sent |
email.accepted (solo API) |
activity.delivered |
email.delivered |
activity.deferred |
email.attempted |
activity.soft_bounced |
email.attempted mentre Emailit ritenta, poi email.bounced se tutti i nuovi tentativi non riescono |
activity.hard_bounced |
email.bounced |
activity.suppressed |
email.suppressed |
activity.opened, activity.opened_unique |
email.loaded, inviato per ogni caricamento |
activity.clicked, activity.clicked_unique |
email.clicked, inviato per ogni clic |
activity.spam_complaint |
email.complained |
activity.unsubscribed |
email.unsubscribed, solo per le email delle campagne |
| Inbound route che inoltra a un webhook | email.received, poi recupera il contenuto con GET /emails/{id} |
Cambia il formato della richiesta:
- MailerSend invia un evento per richiesta. Emailit invia un array JSON di massimo 100 eventi, quindi esegui un ciclo sul corpo.
- In entrambi il nome dell’evento è in
type. In Emailit l’email si trova indata.object: usadata.object.id, l’IDem_della risposta all’invio, al posto didata.message_id(data.email.message.idnei webhook della versione 1), edata.object.toal posto didata.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. - L’header
Signaturedi MailerSend è 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
-
In MailerSend, esporta Hard bounces, Spam complaints, Unsubscribes e Blocklist di ogni dominio, dalle pagine delle suppressions o con l’API (
/v1/suppressions/hard-bounces,/spam-complaints,/unsubscribese/blocklist). La on hold list è temporanea, quindi puoi escluderla. -
Crea un unico CSV con le colonne
email,type,reason:email,type,reason old-address@example.com,recipient,mailersend hard bounce angry@example.com,recipient,mailersend spam complaintUsa il tipo
recipientper gli indirizzi che non devono mai ricevere email. Blocca gli invii via API, SMTP e campagne. Per le persone che si sono disiscritte solo dalle email di marketing, usa il tipounsubscribe, che ferma le campagne ma lascia passare le email transazionali. -
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 ha una sola lista di soppressione per workspace, quindi gli indirizzi di tutti i tuoi domini MailerSend finiscono nella stessa lista. Le soppressioni riguardano indirizzi esatti: i pattern della blocklist come .*@example.com non hanno un equivalente. Vedi Gestisci le soppressioni.
Sposta i template
Copia l’HTML di ogni template dall’editor di MailerSend, poi importalo in Email MarketingTemplates o crealo con l’API dei template. Assegnagli un alias, come receipt, e invialo con "template": "receipt" e variables.
La personalizzazione di MailerSend è una versione limitata di Twig. Temple copre le parti più comuni:
| MailerSend | Emailit (Temple) |
|---|---|
{{ name }}, {{ user.name }} |
{{name}}, {{user.name}} |
{{ name|default('there') }} |
{{name|"there"}} |
{% if plan %}…{% else %}…{% endif %} |
{{#if plan}}…{{else}}…{{/if}} |
{% if plan == "pro" %}, {% elseif %} |
Non supportato. Passa un booleano come is_pro e usa {{#if is_pro}}. |
{% for item in items %}…{% endfor %} |
Non supportato. Genera l’elenco nel tuo codice e passalo come un’unica variabile. |
{{ name|upper }} e altri filtri |
Non supportati. Formatta il valore nel tuo codice. |
personalization[].data |
variables |
MailerSend rimuove la maggior parte dell’HTML dai valori di personalizzazione. Temple non applica mai l’escape all’HTML e non lo rimuove, quindi esegui l’escape dell’input degli utenti prima di passarlo. 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 ms1._domainkey e ms2._domainkey di MailerSend, con il suo CNAME di return path mta né con il suo CNAME di tracciamento email. Mantieni il record DMARC. Vedi Record DNS.
Anche l’inbound routing di MailerSend usa per impostazione predefinita un sottodominio inbound. Se è il tuo caso, assegna alle email in entrata di Emailit un altro sottodominio con inbound_key, oppure cambia il record MX quando sposti la posta in entrata. Vedi Configura le email in entrata.
Dopo il passaggio, rimuovi i record DKIM, di return path e di tracciamento di MailerSend, e togli include:_spf.mailersend.net dal 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