Guida
Migra da Elastic Email
Passa da Elastic Email a Emailit. Fai corrispondere chiamate API v4 e v2, credenziali SMTP e notifiche, converti i merge field e sposta soppressioni, contatti e campagne.
Questa guida fa corrispondere concetti, chiamate API, notifiche, soppressioni, template e contatti di Elastic 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.
Concetti
| Elastic Email | Emailit |
|---|---|
| Account e subaccount | Account e workspace. Ogni workspace ha i propri domini, chiavi, membri e crediti. |
| API key con livelli di accesso | Chiavi API: Full Access, oppure Sending Only facoltativamente limitata a un dominio |
| Credenziali SMTP | La tua chiave API, usata come password SMTP |
| Domini verificati e indirizzi mittente verificati | Domini di invio. Gli indirizzi mittente singoli non sono disponibili. |
| Channel e valori di postback | meta |
| Template, identificati per nome | Template con un alias e versioni |
| Merge field e template scripting | Temple: variabili, valori predefiniti e condizioni |
| Notifiche web HTTP | Webhook |
| Inbound routes | Email in entrata |
| Suppressions e stati dei contatti che bloccano gli invii | Soppressioni |
| Contatti e liste | Contatti e liste |
| Segmenti | Scegli ed escludi le liste in ogni campagna. I segmenti sono in alpha e aperti solo al team di Emailit. |
| Campagne e automazioni | Campagne e automazioni (beta) |
| Moduli | Moduli (accesso anticipato), oppure l’URL di iscrizione di una lista |
| Email verification | Verifica email |
| Private IPs e IP pools | IP dedicati su richiesta |
Elastic Email aggiunge un link di disiscrizione a ogni email, compresi gli invii via API e SMTP. Emailit aggiunge gli header List-Unsubscribe solo alle campagne e alle email di marketing delle automazioni, e il link visibile lo aggiungi tu con {{unsubscribe_url}}. Se invii newsletter o altra posta massiva tramite l’API o SMTP, aggiungi un tuo link e gli header List-Unsubscribe. Vedi Header e metadati.
Aggiorna le chiamate API
POST /v4/emails/transactional di Elastic Email diventa POST /v2/emails. Il corpo è piatto, i nomi dei campi sono in minuscolo e la chiave passa a un header Authorization:
curl https://api.elasticemail.com/v4/emails/transactional \
-H "X-ElasticEmail-ApiKey: $ELASTICEMAIL_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"Recipients": { "To": ["ada@example.com"] },
"Content": {
"From": "Acme <hello@acme.com>",
"Subject": "Your receipt",
"Body": [
{ "ContentType": "HTML", "Content": "<p>Thanks for your order.</p>" },
{ "ContentType": "PlainText", "Content": "Thanks for your order." }
]
}
}'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>"
}'| Elastic Email (API v4) | Emailit |
|---|---|
Header X-ElasticEmail-ApiKey |
Authorization: Bearer secret_… |
Content.From |
from |
Recipients.To, CC, BCC |
to, cc, bcc, fino a 50 ciascuno |
Content.ReplyTo |
reply_to |
Content.Subject |
subject |
Content.Body[] con ContentType HTML e PlainText |
html e text |
Content.Headers |
headers |
Content.Attachments[] con BinaryContent, Name, ContentType |
attachments[] con content, filename, content_type |
Content.AttachFiles (file caricati in precedenza) |
attachments[] con un url che Emailit scarica |
Content.TemplateName |
template, l’alias o l’ID di un template |
Content.Merge |
variables |
Options.ChannelName, Content.Postback |
meta, restituito negli eventi webhook |
Options.TrackOpens, Options.TrackClicks |
tracking: { "loads": true, "clicks": true } |
Options.TimeOffset (minuti) |
scheduled_at (ISO 8601 o inglese semplice) |
Options.PoolName |
Non serve. Un IP dedicato invia tutte le email del suo workspace. |
Content.Utm |
Aggiungi i parametri UTM ai tuoi link. Le campagne li aggiungono per te. |
POST /v4/emails con Recipients[].Fields (unione in blocco) |
Una richiesta per destinatario, ciascuna con le proprie variables |
Header Idempotency-Key |
Header Idempotency-Key, conservato per 24 ore |
Risposta con TransactionID e MessageID |
200 con id (em_…), status: "accepted" e, con più destinatari, ids con un ID per ciascuno |
Se usi ancora l’API v2 (/v2/email/send con un parametro apikey), fai corrispondere i suoi campi del modulo allo stesso modo: from e fromName diventano from, bodyHtml e bodyText diventano html e text, i campi merge_* diventano variables, e template diventa template. Nella v2, ogni indirizzo in to riceve un messaggio separato, come con Bcc. In Emailit, i destinatari in to si vedono a vicenda nell’header To, quindi invia una richiesta per destinatario per tenerli separati. Vedi Invia un’email.
Cambia le impostazioni SMTP
| Impostazione | Elastic Email | Emailit |
|---|---|---|
| Host | smtp.elasticemail.com |
smtp.emailit.com |
| Porta | 2525, 587 o 25 (STARTTLS), 465 (TLS) |
587, 2587, 2525 o 25 (STARTTLS), 465 (TLS) |
| Nome utente | Il nome della credenziale SMTP, un indirizzo email | emailit |
| Password | Il token della credenziale SMTP | La tua chiave API di Emailit |
Emailit non legge gli header di controllo di Elastic Email, come X-ElasticEmail-Channel, X-ElasticEmail-Postback, IsTransactional, trackopens o trackclicks. Rimuovili e imposta invece il tracciamento sul dominio. Vedi Impostazioni SMTP.
Fai corrispondere gli eventi webhook
| Notifica di Elastic Email | Evento Emailit |
|---|---|
Sent (il server del destinatario ha accettato il messaggio) |
email.delivered |
Opened |
email.loaded |
Clicked |
email.clicked |
Error |
email.bounced per gli errori permanenti. Per gli errori temporanei viene inviato email.attempted mentre Emailit ritenta. |
AbuseReport |
email.complained |
Unsubscribed |
email.unsubscribed, solo per le email delle campagne |
| Inbound route che notifica un URL | email.received, poi recupera il contenuto con GET /emails/{id} |
Emailit invia anche email.accepted quando l’API accetta un’email, ed email.suppressed quando una soppressione recipient blocca un indirizzo. Vedi Tipi di evento.
Cambia il formato della richiesta:
- Elastic Email invia un evento per richiesta, nella query string o come oggetto JSON piatto. Emailit invia un array JSON di massimo 100 eventi, quindi esegui un ciclo sul corpo.
- Il nome dell’evento passa da
statusatype, e l’email si trova indata.object. Usadata.object.id, l’IDem_della risposta all’invio, al posto dimessageid, edata.object.toal posto dito. I tuoi valorimeta, che sostituisconochannelepostback, 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. - Emailit firma ogni richiesta. Verifica
X-Emailit-Signature, l’HMAC-SHA256 in esadecimale di<timestamp>.<raw body>, rispetto aX-Emailit-Timestampe al tuo secretwhsec_. Anche la firma facoltativa di Elastic Email usa secretwhsec_, ma firma una stringa diversa, quindi aggiorna il codice di verifica. 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 gli indirizzi che Elastic Email blocca, da Suppressions nel pannello o con l’API (
/v4/suppressions/bounces,/complaintse/unsubscribes). -
Crea un unico CSV con le colonne
email,type,reason:Stato in Elastic Email Tipo in Emailit Invalid ( Bounced)recipientComplaint ( Abuse)recipientUnsubscribed unsubscribe, che ferma le campagne ma lascia passare le email transazionali. Usarecipientper bloccare tutte le email.email,type,reason old-address@example.com,recipient,elastic email bounced left@example.com,unsubscribe,elastic email unsubscribed -
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.
Vedi Gestisci le soppressioni.
Sposta contatti e campagne
Esporta i contatti da Contacts (selezionali, poi More actions > Export) o con POST /v4/contacts/export, ed esporta ogni lista a cui invii campagne. Poi spostali in base allo stato:
| Stato in Elastic Email | Dove va |
|---|---|
| Engaged, Active | Importali nella lista corrispondente in Email MarketingContacts con Import. |
| Transactional | Lasciali fuori dalle liste. Non si sono mai iscritti alle tue email di marketing. |
| Invalid, Complaint, Unsubscribed | Nella lista di soppressione, come sopra. |
| Inactive, Stale, Not Confirmed | Lasciali fuori. |
Prima dell’importazione crea i campi personalizzati per i campi dei tuoi contatti, e dividi i file in parti di massimo 2500 righe. L’importazione aggiunge come iscritte tutte le persone nel file, quindi importa solo chi deve ricevere le tue campagne. Vedi Importa ed esporta i contatti.
Ricrea campagne e automazioni in Email MarketingCampaigns e Automations, partendo dai template importati.
Sposta i template
Copia l’HTML di ogni template con Edit as HTML in Elastic Email, oppure recuperalo con GET /v4/templates/{name}, che lo restituisce in Body. Importalo in Email MarketingTemplates o crealo con l’API dei template, e usa il nome del template come alias se rispetta il formato degli alias: lettere minuscole, numeri, - e _.
I merge field di Elastic Email usano parentesi graffe singole, Temple usa le doppie. I campi con parentesi singole rimasti in un template vengono inviati come testo semplice, quindi convertili tutti:
| Elastic Email | Emailit (Temple) |
|---|---|
{firstname}, {lastname}, {email} |
{{first_name}}, {{last_name}}, {{email}} nelle campagne. Negli invii via API, i nomi che passi in variables. |
{firstname:friend} |
{{first_name|"friend"}} |
{company} o un altro campo personalizzato |
{{cf.company}} nelle campagne |
{unsubscribe} |
{{unsubscribe_url}} nelle campagne |
{contactprofile} |
{{manage_subscriptions_url}} nelle campagne |
{view} |
{{webview_url}} nelle campagne |
{accountaddress} e gli altri campi dell’account |
Scrivili nel template, oppure tienili nei valori globali |
Template scripting in {{ … }} |
Non supportato. Calcola i valori nel tuo codice e usa {{#if}} per i contenuti condizionali. |
Vedi Tag di unione e 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 il record DKIM api._domainkey di Elastic Email, con il suo CNAME tracking né con un dominio di bounce personalizzato. Mantieni il record DMARC. Vedi Record DNS.
Dopo il passaggio, rimuovi i record DKIM e di tracciamento di Elastic Email e togli include:_spf.elasticemail.com dal record SPF. Se ricevi posta con le inbound routes di Elastic Email, spostala prima su un sottodominio di ricezione di Emailit. Emailit riceve su un sottodominio, come inbound.acme.com, quindi gli indirizzi di ricezione cambiano.
Passaggi successivi
- Checklist per andare in produzione
- Configura un webhook
- Migrazione prioritaria: lascia che i tecnici di Emailit facciano la migrazione insieme a te