# 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](/it/docs/migrate/) per l’ordine generale e per sapere come usare entrambi i provider in parallelo.

## Concetti

| SparkPost | Emailit |
| --- | --- |
| Primary account e subaccounts | Account e [workspace](/it/docs/workspaces/). 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](/it/docs/developers/api-keys/): **Full Access**, oppure **Sending Only** facoltativamente limitata a un dominio |
| Sending domains | [Domini di invio](/it/docs/domains/) |
| Bounce domains | Il return path `emailit.<your domain>`, che ogni dominio ha |
| Tracking domains | [Sottodominio di tracciamento](/it/docs/tracking/), come `go.acme.com` |
| Transmissions | [Email](/it/docs/email-api/), una richiesta per messaggio |
| Stored recipient lists | [Liste](/it/docs/audiences/) e [campagne](/it/docs/campaigns/) |
| Templates e snippets | [Template](/it/docs/templates/) con un alias e versioni. Non ci sono snippet. |
| Event webhooks | [Webhook](/it/docs/webhooks/) |
| Inbound domains e relay webhooks | [Email in entrata](/it/docs/inbound/) |
| Suppression list | [Soppressioni](/it/docs/suppressions/) |
| `metadata`, `tags`, `campaign_id` | `meta` |
| `options.sandbox` | Nessuna modalità di test. I nuovi workspace sono in [modalità sandbox](/it/docs/workspaces/production-access/) e consegnano solo ai membri del workspace. |
| IP pools | [IP dedicati](/it/docs/deliverability/dedicated-ips/) 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`:

```bash title="Prima: SparkPost"
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>"
    }
  }'
```

```bash title="Dopo: Emailit"
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: `, senza `Bearer` | `Authorization: Bearer secret_…` |
| `content.from`, una stringa o `{ email, name }` | `from: "Name "` |
| `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](/it/docs/smtp/) |
| `recipients: { "list_id": "…" }` | Una [campagna](/it/docs/campaigns/) 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](/it/docs/email-api/send-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](/it/docs/smtp/settings/).

## 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}`](/it/docs/api-reference/emails/get/) |

Cambia il formato della richiesta:

- Entrambi inviano un array JSON di eventi. SparkPost racchiude ogni evento in `msys` e in una classe come `message_event`. Emailit mette il nome in `type` e l’email in `data.object`, con un massimo di 100 eventi per richiesta.
- Usa `data.object.id`, l’ID `em_` della risposta all’invio, al posto di `message_id` e `transmission_id`, e `data.object.to` al posto di `rcpt_to`. I tuoi valori `meta`, che sostituiscono `rcpt_meta` e `rcpt_tags`, sono in `data.object.meta`.
- Per `email.loaded` ed `email.clicked`, `data.object` è il caricamento o il clic. Usa `data.object.email_id` per l’ID dell’email, e `data.object.email.rcpt_to` e `data.object.email.meta` per il destinatario e i tuoi valori `meta`.
- SparkPost protegge i webhook con autenticazione basic o OAuth 2.0, senza firma. Emailit firma ogni richiesta: verifica `X-Emailit-Signature` rispetto a `X-Emailit-Timestamp` e al tuo secret `whsec_`. Vedi [Verifica le firme dei webhook](/it/docs/webhooks/request-signature/).

```javascript
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

1. Esporta la lista di soppressione con `GET /api/v1/suppression-list?per_page=10000&cursor=initial` e segui il cursore finché non hai tutte le pagine. Include le voci dei tuoi subaccount, ciascuna con il suo `subaccount_id`.

2. Crea un unico CSV con le colonne `email,type,reason`:

   | Voce di SparkPost | Tipo in Emailit |
   | --- | --- |
   | `transactional`, o entrambi i tipi | `recipient`, che blocca gli invii via API, SMTP e campagne |
   | Solo `non_transactional` | `unsubscribe`, che ferma le campagne ma lascia passare le email transazionali |
   | `open_tracking` | Escludila. Non blocca l’invio. |

```csv
email,type,reason
old-address@example.com,recipient,sparkpost bounce rule
left@example.com,unsubscribe,sparkpost unsubscribe link
```

3. In **Email API → Suppressions**, 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](/it/docs/suppressions/manage/).

## 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 Marketing → Templates** o crealo con l’[API dei template](/it/docs/api-reference/templates/create/), 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](/it/docs/templates/temple/) e [Importa ed esporta i template](/it/docs/templates/import-export/).

## Cambia i DNS

Aggiungi il dominio in **Email API → Domains** 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](/it/docs/domains/dns-records/).

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](/it/docs/tracking/custom-tracking-domain/) e [Configura le email in entrata](/it/docs/inbound/set-up/).

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](/it/docs/get-started/go-live/)
- [Configura un webhook](/it/docs/webhooks/set-up/)
- [Migrazione prioritaria](/it/docs/programs/priority-migration/): lascia che i tecnici di Emailit facciano la migrazione insieme a te

---
Fonte: https://emailit.com/it/docs/migrate/sparkpost/
