Guida
Migra da SparkPost
Passa da SparkPost (ora Bird Email) a Emailit. Converti transmissions e substitution data, cambia le impostazioni SMTP_Injection e sposta webhook di eventi, soppressioni, template e DNS.
Questa guida fa corrispondere concetti, chiamate API, webhook, soppressioni e template di SparkPost ai loro equivalenti in Emailit. SparkPost ora fa parte di Bird ed è venduto come Bird Email, e l’API di SparkPost su api.sparkpost.com è ancora attiva. Questa guida tratta quell’API. Leggi prima Passa a Emailit per l’ordine generale e per sapere come usare entrambi i provider in parallelo.
Concetti
| SparkPost | Emailit |
|---|---|
| Primary account e subaccounts | Account e workspace. Ogni workspace ha i propri domini, chiavi, membri e crediti. |
| Account USA e UE, su host API separati | Un solo host API, api.emailit.com |
| API keys con grants | Chiavi API: Full Access, oppure Sending Only facoltativamente limitata a un dominio |
| Sending domains | Domini di invio |
| Bounce domains | Il return path emailit.<your domain>, che ogni dominio ha |
| Tracking domains | Sottodominio di tracciamento, come go.acme.com |
| Transmissions | Email, una richiesta per messaggio |
| Stored recipient lists | Liste e campagne |
| Templates e snippets | Template con un alias e versioni. Non ci sono snippet. |
| Event webhooks | Webhook |
| Inbound domains e relay webhooks | Email in entrata |
| Suppression list | Soppressioni |
metadata, tags, campaign_id |
meta |
options.sandbox |
Nessuna modalità di test. I nuovi workspace sono in modalità sandbox e consegnano solo ai membri del workspace. |
| IP pools | IP dedicati su richiesta |
Aggiorna le chiamate API
POST /api/v1/transmissions di SparkPost diventa POST /v2/emails. Il contenuto passa al livello principale, e i destinatari diventano to, cc e bcc:
curl https://api.sparkpost.com/api/v1/transmissions \
-H "Authorization: $SPARKPOST_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"recipients": [{ "address": { "email": "ada@example.com" } }],
"content": {
"from": { "email": "hello@acme.com", "name": "Acme" },
"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>"
}'| SparkPost | Emailit |
|---|---|
Authorization: <API key>, senza Bearer |
Authorization: Bearer secret_… |
content.from, una stringa o { email, name } |
from: "Name <email>" |
recipients[].address |
to, una stringa o un array di massimo 50 indirizzi |
Cc e Bcc come destinatari aggiuntivi con header_to e un header CC |
cc e bcc |
content.reply_to |
reply_to |
content.subject, content.text, content.html |
subject, text, html |
content.headers |
headers |
content.attachments[] con name, type, data |
attachments[] con filename, content_type, content |
content.inline_images[] |
attachments[] con un content_id, richiamato come cid: nell’HTML |
content.template_id |
template: un alias invia la versione pubblicata, e un ID tem_ invia esattamente quella versione, che sia una bozza o no |
substitution_data |
variables |
metadata, recipients[].tags, campaign_id |
meta, un oggetto di valori stringa, restituito negli eventi webhook |
options.open_tracking, options.click_tracking |
tracking: { "loads": true, "clicks": true } |
options.start_time (fino a 3 giorni in anticipo) |
scheduled_at (ISO 8601 o inglese semplice) |
options.transactional |
Non serve. Le email inviate con l’API non ricevono mai header List-Unsubscribe, a meno che non li aggiunga tu. |
content.email_rfc822 |
Invia il messaggio MIME tramite l’SMTP relay |
recipients: { "list_id": "…" } |
Una campagna a una lista |
Header Idempotency-Key |
Header Idempotency-Key, conservato per 24 ore |
Risposta con l’id della transmission e il numero di destinatari |
200 con id (em_…), status: "accepted" e, con più destinatari, ids con un ID per ciascuno |
SparkPost invia un messaggio separato a ogni destinatario di una transmission, e nessuno vede gli altri indirizzi. In Emailit, tutti gli indirizzi in to e cc compaiono negli header di ogni copia. Per tenere separati i destinatari, o per dare a ciascuno i propri substitution_data, invia una richiesta per destinatario. Ottieni subito gli ID delle email, invece di trovare gli ID dei messaggi negli eventi successivi. Vedi Invia un’email.
Cambia le impostazioni SMTP
| Impostazione | SparkPost | Emailit |
|---|---|---|
| Host | smtp.sparkpostmail.com, oppure smtp.eu.sparkpostmail.com |
smtp.emailit.com |
| Porta | 587 o 2525 (STARTTLS) |
587, 2587, 2525 o 25 (STARTTLS), 465 (TLS) |
| Nome utente | SMTP_Injection |
emailit |
| Password | Una chiave API con il permesso Send via SMTP | La tua chiave API di Emailit |
Emailit non legge l’header X-MSYS-API. Rimuovilo. Inserisci gli indirizzi Cc e Bcc nel messaggio come normali destinatari, imposta il tracciamento sul dominio e usa l’API quando ti servono i metadati. Vedi Impostazioni SMTP.
Fai corrispondere gli eventi webhook
| Evento SparkPost | Evento Emailit |
|---|---|
injection |
email.accepted (solo API) |
delivery |
email.delivered |
delay |
email.attempted |
bounce, out_of_band |
email.bounced |
policy_rejection |
email.suppressed quando l’indirizzo ha una soppressione recipient |
generation_failure, generation_rejection |
Nessun evento. Problemi come un template sconosciuto sono errori nella risposta dell’API. |
spam_complaint |
email.complained |
open, initial_open |
email.loaded |
click |
email.clicked |
list_unsubscribe, link_unsubscribe |
email.unsubscribed, solo per le email delle campagne |
| Relay webhook | email.received, poi recupera il contenuto con GET /emails/{id} |
Cambia il formato della richiesta:
- Entrambi inviano un array JSON di eventi. SparkPost racchiude ogni evento in
msyse in una classe comemessage_event. Emailit mette il nome intypee l’email indata.object, con un massimo di 100 eventi per richiesta. - Usa
data.object.id, l’IDem_della risposta all’invio, al posto dimessage_idetransmission_id, edata.object.toal posto dircpt_to. I tuoi valorimeta, che sostituisconorcpt_metaercpt_tags, 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. - SparkPost protegge i webhook con autenticazione basic o OAuth 2.0, senza firma. Emailit firma ogni richiesta: verifica
X-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 la lista di soppressione con
GET /api/v1/suppression-list?per_page=10000&cursor=initiale segui il cursore finché non hai tutte le pagine. Include le voci dei tuoi subaccount, ciascuna con il suosubaccount_id. -
Crea un unico CSV con le colonne
email,type,reason:Voce di SparkPost Tipo in Emailit transactional, o entrambi i tipirecipient, che blocca gli invii via API, SMTP e campagneSolo non_transactionalunsubscribe, che ferma le campagne ma lascia passare le email transazionaliopen_trackingEscludila. Non blocca l’invio. email,type,reason old-address@example.com,recipient,sparkpost bounce rule left@example.com,unsubscribe,sparkpost unsubscribe link -
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.
Se usavi i subaccount, dividi il file per subaccount e importa ogni parte nel workspace corrispondente. Vedi Gestisci le soppressioni.
Sposta i template
Recupera ogni template pubblicato con GET /api/v1/templates/{id}?draft=false, che restituisce content.html, content.text e content.subject. Importalo in Email MarketingTemplates o crealo con l’API dei template, e usa l’ID del template di SparkPost come alias, se rispetta il formato degli alias: lettere minuscole, numeri, - e _.
Converti il linguaggio di template di SparkPost in Temple:
| SparkPost | Emailit (Temple) |
|---|---|
{{name}}, {{order.total}} |
Uguale |
{{address.name}}, {{address.email}} (il destinatario) |
Passali in variables, ad esempio come name e email |
{{{html_block}}} |
{{html_block}}. Temple non applica mai l’escape all’HTML, quindi esegui tu l’escape dell’input degli utenti. |
{{name or 'Customer'}} |
{{name|"Customer"}} |
{{if plan}}…{{else}}…{{end}} |
{{#if plan}}…{{else}}…{{/if}} |
{{if plan == 'pro'}}, {{elseif}}, and, or |
Non supportato. Passa un booleano come is_pro e usa {{#if is_pro}}. |
{{each items}}…{{end}} |
Non supportato. Genera l’elenco nel tuo codice e passalo come un’unica variabile. |
render_snippet(), render_dynamic_content() |
Non supportato. Inserisci il contenuto nel template, oppure passalo come variabile. |
substitution_data |
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 SparkPost (un selettore come scph0316._domainkey), con il CNAME del suo dominio di bounce né con quello del suo dominio di tracciamento. Mantieni il record DMARC. Vedi Record DNS.
Se il dominio di tracciamento o il dominio di ricezione di SparkPost usa già il nome go o inbound, scegli altri nomi per Emailit con tracking_key e inbound_key. Vedi Configura un dominio di tracciamento personalizzato e Configura le email in entrata.
Dopo il passaggio, rimuovi i record DKIM, di bounce e di tracciamento di SparkPost. Se ricevi posta con i relay webhook, spostala prima su un sottodominio di ricezione di Emailit, poi rimuovi i record MX rx1, rx2 e rx3 di SparkPost.
Passaggi successivi
- Checklist per andare in produzione
- Configura un webhook
- Migrazione prioritaria: lascia che i tecnici di Emailit facciano la migrazione insieme a te