Guide
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 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. 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 : Full Access, ou Sending Only, éventuellement restreinte à un domaine |
| Domaines d’envoi (sending domains) | Domaines d’envoi |
| Domaines de rebond (bounce domains) | Le return-path emailit.<your domain>, dont chaque domaine dispose |
| Domaines de suivi (tracking domains) | Sous-domaine de suivi, comme go.acme.com |
| Transmissions | E-mails, une requête par message |
| Listes de destinataires enregistrées (stored recipient lists) | Listes de contacts et campagnes |
| Modèles et snippets | Modèles avec un alias et des versions. Il n’y a pas de snippets. |
| Webhooks d’événements | Webhooks |
| Domaines de réception (inbound domains) et relay webhooks | E-mails entrants |
| Suppression list | Adresses bloquées |
metadata, tags, campaign_id |
meta |
options.sandbox |
Pas de mode test. Les nouveaux espaces de travail sont en mode bac à sable et ne livrent qu’aux membres de l’espace de travail. |
| Pools d’IP | IP dédiées 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 :
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>, sans Bearer |
Authorization: Bearer secret_… |
content.from, une chaîne ou { email, name } |
from: "Name <email>" |
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 |
recipients: { "list_id": "…" } |
Une campagne 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.
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.
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} |
Le format des requêtes change :
- Les deux envoient (POST) un tableau JSON d’événements. SparkPost enveloppe chaque événement dans
msyset une classe commemessage_event. Emailit place le nom danstypeet l’e-mail dansdata.object, avec 100 événements au maximum par requête. - Utilisez
data.object.id, l’IDem_de la réponse d’envoi, au lieu demessage_idettransmission_id, etdata.object.toau lieu dercpt_to. Vos valeursmeta, qui remplacentrcpt_metaetrcpt_tags, se trouvent dansdata.object.meta. - Pour
email.loadedetemail.clicked,data.objectest le chargement ou le clic. Utilisezdata.object.email_idpour l’ID de l’e-mail, etdata.object.email.rcpt_toetdata.object.email.metapour le destinataire et vos valeursmeta. - 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 deX-Emailit-Timestampet de votre secretwhsec_. Consultez Signature des requêtes.
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
-
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 sonsubaccount_id. -
Constituez un seul CSV avec les colonnes
email,type,reason:Entrée SparkPost Type Emailit transactional, ou les deux typesrecipient, qui bloque les envois par l’API, par SMTP et par les campagnesnon_transactionaluniquementunsubscribe, qui arrête les campagnes mais laisse passer les e-mails transactionnelsopen_trackingLaissez-la de côté. Elle ne bloque pas l’envoi. email,type,reason old-address@example.com,recipient,sparkpost bounce rule left@example.com,unsubscribe,sparkpost unsubscribe link -
Dans Email APISuppressions, 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.
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 MarketingTemplates ou créez-le avec l’API des modèles, 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 et Importer et exporter des modèles.
Modifier le DNS
Ajoutez votre domaine dans Email APIDomains 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.
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é et Configurer la réception.
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
- Configurer des webhooks
- Migration prioritaire : laissez les ingénieurs d’Emailit effectuer la migration avec vous