# Migrer depuis SparkPost

> Passez de SparkPost (désormais Bird Email) à Emailit. Convertissez les transmissions et les substitution data, remplacez les paramètres SMTP_Injection, et transférez les webhooks d’événements, les adresses bloquées, les modèles et le DNS.

Ce guide fait correspondre les concepts, les appels API, les webhooks, les adresses bloquées et les modèles de SparkPost à leurs équivalents dans Emailit. SparkPost fait désormais partie de Bird et est vendu sous le nom Bird Email, et l’API SparkPost à l’adresse `api.sparkpost.com` fonctionne toujours. Ce guide porte sur cette API. Lisez d’abord [Migrer vers Emailit](/fr/docs/migrate/) pour l’ordre général et la façon de faire fonctionner les deux fournisseurs en parallèle.

## Concepts

| SparkPost | Emailit |
| --- | --- |
| Compte principal et sous-comptes (subaccounts) | Compte et [espaces de travail](/fr/docs/workspaces/). Chaque espace de travail a ses propres domaines, clés, membres et crédits. |
| Comptes US et UE, sur des hôtes d’API distincts | Un seul hôte d’API, `api.emailit.com` |
| Clés API avec des autorisations (grants) | [Clés API](/fr/docs/developers/api-keys/) : **Full Access**, ou **Sending Only**, éventuellement restreinte à un domaine |
| Domaines d’envoi (sending domains) | [Domaines d’envoi](/fr/docs/domains/) |
| Domaines de rebond (bounce domains) | Le return-path `emailit.<your domain>`, dont chaque domaine dispose |
| Domaines de suivi (tracking domains) | [Sous-domaine de suivi](/fr/docs/tracking/), comme `go.acme.com` |
| Transmissions | [E-mails](/fr/docs/email-api/), une requête par message |
| Listes de destinataires enregistrées (stored recipient lists) | [Listes de contacts](/fr/docs/audiences/) et [campagnes](/fr/docs/campaigns/) |
| Modèles et snippets | [Modèles](/fr/docs/templates/) avec un alias et des versions. Il n’y a pas de snippets. |
| Webhooks d’événements | [Webhooks](/fr/docs/webhooks/) |
| Domaines de réception (inbound domains) et relay webhooks | [E-mails entrants](/fr/docs/inbound/) |
| Suppression list | [Adresses bloquées](/fr/docs/suppressions/) |
| `metadata`, `tags`, `campaign_id` | `meta` |
| `options.sandbox` | Pas de mode test. Les nouveaux espaces de travail sont en [mode bac à sable](/fr/docs/workspaces/production-access/) et ne livrent qu’aux membres de l’espace de travail. |
| Pools d’IP | [IP dédiées](/fr/docs/deliverability/dedicated-ips/) sur demande |

## Mettre à jour vos appels API

Le `POST /api/v1/transmissions` de SparkPost devient `POST /v2/emails`. Le contenu passe au premier niveau, et les destinataires deviennent `to`, `cc` et `bcc` :

```bash title="Before: 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="After: 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: `, sans `Bearer` | `Authorization: Bearer secret_…` |
| `content.from`, une chaîne ou `{ email, name }` | `from: "Name "` |
| `recipients[].address` | `to`, une chaîne ou un tableau de 50 adresses au maximum |
| Cc et Bcc sous forme de destinataires supplémentaires, avec `header_to` et un en-tête `CC` | `cc` et `bcc` |
| `content.reply_to` | `reply_to` |
| `content.subject`, `content.text`, `content.html` | `subject`, `text`, `html` |
| `content.headers` | `headers` |
| `content.attachments[]` avec `name`, `type`, `data` | `attachments[]` avec `filename`, `content_type`, `content` |
| `content.inline_images[]` | `attachments[]` avec un `content_id`, référencé sous la forme `cid:` dans le HTML |
| `content.template_id` | `template` : un alias envoie la version publiée, et un ID `tem_` envoie exactement cette version, brouillon ou non |
| `substitution_data` | `variables` |
| `metadata`, `recipients[].tags`, `campaign_id` | `meta`, un objet de valeurs de type chaîne, renvoyé dans les événements webhook |
| `options.open_tracking`, `options.click_tracking` | `tracking: { "loads": true, "clicks": true }` |
| `options.start_time` (jusqu’à 3 jours à l’avance) | `scheduled_at` (ISO 8601 ou anglais courant) |
| `options.transactional` | Inutile. Les e-mails envoyés par l’API ne reçoivent jamais d’en-têtes `List-Unsubscribe`, sauf si vous les ajoutez. |
| `content.email_rfc822` | Envoyez le message MIME via le [relais SMTP](/fr/docs/smtp/) |
| `recipients: { "list_id": "…" }` | Une [campagne](/fr/docs/campaigns/) vers une liste de contacts |
| En-tête `Idempotency-Key` | En-tête `Idempotency-Key`, conservé 24 heures |
| Réponse avec l’`id` de la transmission et le nombre de destinataires | `200` avec `id` (`em_…`), `status: "accepted"` et, pour plusieurs destinataires, `ids` avec un ID par destinataire |

SparkPost envoie un message distinct à chaque destinataire d’une transmission, et personne ne voit les autres adresses. Dans Emailit, toutes les adresses de `to` et `cc` apparaissent dans les en-têtes de chaque copie. Pour séparer les destinataires, ou pour donner à chacun ses propres `substitution_data`, envoyez une requête par destinataire. Vous obtenez les ID des e-mails immédiatement, au lieu de retrouver les ID de message dans des événements ultérieurs. Consultez [Envoyer un e-mail](/fr/docs/email-api/send-email/).

## Changer les paramètres SMTP

| Paramètre | SparkPost | Emailit |
| --- | --- | --- |
| Hôte | `smtp.sparkpostmail.com`, ou `smtp.eu.sparkpostmail.com` | `smtp.emailit.com` |
| Port | `587` ou `2525` (STARTTLS) | `587`, `2587`, `2525` ou `25` (STARTTLS), `465` (TLS) |
| Nom d’utilisateur | `SMTP_Injection` | `emailit` |
| Mot de passe | Une clé API avec la permission **Send via SMTP** | Votre clé API Emailit |

Emailit ne lit pas l’en-tête `X-MSYS-API`. Supprimez-le. Placez les adresses Cc et Bcc dans le message comme des destinataires normaux, réglez le suivi au niveau du domaine, et utilisez l’API quand vous avez besoin de métadonnées. Consultez [Paramètres SMTP](/fr/docs/smtp/settings/).

## Faire correspondre les événements webhook

| Événement SparkPost | Événement Emailit |
| --- | --- |
| `injection` | `email.accepted` (API uniquement) |
| `delivery` | `email.delivered` |
| `delay` | `email.attempted` |
| `bounce`, `out_of_band` | `email.bounced` |
| `policy_rejection` | `email.suppressed` quand l’adresse a un blocage de type `recipient` |
| `generation_failure`, `generation_rejection` | Pas d’événement. Les problèmes comme un modèle inconnu sont des erreurs dans la réponse de l’API. |
| `spam_complaint` | `email.complained` |
| `open`, `initial_open` | `email.loaded` |
| `click` | `email.clicked` |
| `list_unsubscribe`, `link_unsubscribe` | `email.unsubscribed`, pour les e-mails de campagne uniquement |
| Relay webhook | `email.received`, puis récupérez le contenu avec [`GET /emails/{id}`](/fr/docs/api-reference/emails/get/) |

Le format des requêtes change :

- Les deux envoient (POST) un tableau JSON d’événements. SparkPost enveloppe chaque événement dans `msys` et une classe comme `message_event`. Emailit place le nom dans `type` et l’e-mail dans `data.object`, avec 100 événements au maximum par requête.
- Utilisez `data.object.id`, l’ID `em_` de la réponse d’envoi, au lieu de `message_id` et `transmission_id`, et `data.object.to` au lieu de `rcpt_to`. Vos valeurs `meta`, qui remplacent `rcpt_meta` et `rcpt_tags`, se trouvent dans `data.object.meta`.
- Pour `email.loaded` et `email.clicked`, `data.object` est le chargement ou le clic. Utilisez `data.object.email_id` pour l’ID de l’e-mail, et `data.object.email.rcpt_to` et `data.object.email.meta` pour le destinataire et vos valeurs `meta`.
- SparkPost protège les webhooks par une authentification basique ou OAuth 2.0, sans signature. Emailit signe chaque requête : vérifiez `X-Emailit-Signature` à l’aide de `X-Emailit-Timestamp` et de votre secret `whsec_`. Consultez [Signature des requêtes](/fr/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);
}
```

## Transférer les adresses bloquées

1. Exportez la liste d’adresses bloquées avec `GET /api/v1/suppression-list?per_page=10000&cursor=initial`, et suivez le curseur jusqu’à obtenir toutes les pages. Elle inclut les entrées de vos sous-comptes, chacune avec son `subaccount_id`.

2. Constituez un seul CSV avec les colonnes `email,type,reason` :

   | Entrée SparkPost | Type Emailit |
   | --- | --- |
   | `transactional`, ou les deux types | `recipient`, qui bloque les envois par l’API, par SMTP et par les campagnes |
   | `non_transactional` uniquement | `unsubscribe`, qui arrête les campagnes mais laisse passer les e-mails transactionnels |
   | `open_tracking` | Laissez-la de côté. Elle ne bloque pas l’envoi. |

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

3. Dans **Email API → Suppressions**, sélectionnez **Import** et chargez le fichier. Chaque fichier peut contenir 10 000 lignes et peser 8 Mo au maximum. Les doublons sont ignorés.

Si vous utilisiez des sous-comptes, découpez le fichier par sous-compte et importez chaque partie dans l’espace de travail correspondant. Consultez [Gérer les adresses bloquées](/fr/docs/suppressions/manage/).

## Transférer les modèles

Récupérez chaque modèle publié avec `GET /api/v1/templates/{id}?draft=false`, qui renvoie `content.html`, `content.text` et `content.subject`. Importez-le dans **Email Marketing → Templates** ou créez-le avec l’[API des modèles](/fr/docs/api-reference/templates/create/), et utilisez l’ID du modèle SparkPost comme alias s’il respecte le format des alias : lettres minuscules, chiffres, `-` et `_`.

Convertissez le langage de modèles de SparkPost en Temple :

| SparkPost | Emailit (Temple) |
| --- | --- |
| `{{name}}`, `{{order.total}}` | Identique |
| `{{address.name}}`, `{{address.email}}` (le destinataire) | Transmettez-les dans `variables`, par exemple sous les noms `name` et `email` |
| `{{{html_block}}}` | `{{html_block}}`. Temple n’échappe jamais le HTML : échappez vous-même les saisies des utilisateurs. |
| `{{name or 'Customer'}}` | `{{name\|"Customer"}}` |
| `{{if plan}}…{{else}}…{{end}}` | `{{#if plan}}…{{else}}…{{/if}}` |
| `{{if plan == 'pro'}}`, `{{elseif}}`, `and`, `or` | Non pris en charge. Transmettez un booléen comme `is_pro` et utilisez `{{#if is_pro}}`. |
| `{{each items}}…{{end}}` | Non pris en charge. Générez la liste dans votre code et transmettez-la comme une seule variable. |
| `render_snippet()`, `render_dynamic_content()` | Non pris en charge. Placez le contenu dans le modèle, ou transmettez-le comme variable. |
| `substitution_data` | `variables` |

Consultez [Temple](/fr/docs/templates/temple/) et [Importer et exporter des modèles](/fr/docs/templates/import-export/).

## Modifier le DNS

Ajoutez votre domaine dans **Email API → Domains** et publiez les enregistrements Emailit. Ils utilisent leurs propres noms (`emailit._domainkey`, `emailit.<domain>`, et éventuellement `go` et `inbound`) : ils n’entrent donc pas en conflit avec l’enregistrement DKIM de SparkPost (un sélecteur comme `scph0316._domainkey`), son CNAME de domaine de rebond ni son CNAME de domaine de suivi. Conservez votre enregistrement DMARC. Consultez [Enregistrements DNS](/fr/docs/domains/dns-records/).

Si votre domaine de suivi ou votre domaine de réception SparkPost utilise déjà le nom `go` ou `inbound`, choisissez d’autres noms pour Emailit avec `tracking_key` et `inbound_key`. Consultez [Domaine de suivi personnalisé](/fr/docs/tracking/custom-tracking-domain/) et [Configurer la réception](/fr/docs/inbound/set-up/).

Après la bascule, supprimez les enregistrements DKIM, de rebond et de suivi de SparkPost. Si vous recevez des e-mails avec des relay webhooks, déplacez-les d’abord vers un sous-domaine de réception Emailit, puis supprimez les enregistrements MX `rx1`, `rx2` et `rx3` de SparkPost.

## Étapes suivantes

- [Liste de contrôle avant la mise en production](/fr/docs/get-started/go-live/)
- [Configurer des webhooks](/fr/docs/webhooks/set-up/)
- [Migration prioritaire](/fr/docs/programs/priority-migration/) : laissez les ingénieurs d’Emailit effectuer la migration avec vous

---
Source: https://emailit.com/fr/docs/migrate/sparkpost/
