Guide
Migrer depuis Mandrill
Passez de Mandrill (Mailchimp Transactional) à Emailit. Faites correspondre les clés API et les sous-comptes, convertissez les appels messages/send, remplacez les paramètres SMTP et les en-têtes X-MC, vérifiez les webhooks et transférez les rejets.
Ce guide fait correspondre les concepts, les appels API, les webhooks, la liste de rejet (rejection denylist) et les modèles de Mandrill (Mailchimp Transactional Email) à leurs équivalents dans Emailit. 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. Si vous envoyez aussi des campagnes depuis Mailchimp, consultez Migrer depuis Mailchimp.
Concepts
| Mandrill | Emailit |
|---|---|
| Un forfait Mailchimp Standard ou Premium avec des blocs transactionnels | Un compte Emailit. Vous n’avez pas besoin d’un forfait marketing pour envoyer des e-mails transactionnels. |
| Sous-comptes (subaccounts) | Espaces de travail, chacun avec ses propres domaines, clés, limites et crédits |
| Clés API | Clés API : Full Access, ou Sending Only, éventuellement restreinte à un domaine |
| Clés API de test | Pas de mode test. Les nouveaux espaces de travail sont en mode bac à sable et ne peuvent envoyer qu’aux membres de l’espace de travail. |
| Domaines d’envoi et vérification DKIM/SPF | Domaines d’envoi |
| Domaines de suivi (tracking domains) | Sous-domaine de suivi, comme go.acme.com |
Modèles avec des zones mc:edit |
Modèles avec un alias et des versions, dont le rendu est effectué avec Temple |
| Webhooks | Webhooks |
| Domaines et routes de réception (inbound) | E-mails entrants |
| Rejection denylist | Adresses bloquées |
| Rejection allowlist | Non disponible |
| Langages de fusion : Mailchimp et Handlebars | Temple |
| Tags et métadonnées | meta |
| Outbound activity | Email APIEmails et Email APILogs |
| IP dédiées et pools d’IP | IP dédiées sur demande |
Mettre à jour vos appels API
Le POST /messages/send de Mandrill reçoit la clé API dans le corps JSON et imbrique l’e-mail dans message. Le POST /v2/emails d’Emailit reçoit un jeton bearer et un corps plat :
curl https://mandrillapp.com/api/1.0/messages/send \
-H "Content-Type: application/json" \
-d '{
"key": "'"$MANDRILL_API_KEY"'",
"message": {
"from_email": "hello@acme.com",
"from_name": "Acme",
"to": [{ "email": "ada@example.com", "type": "to" }],
"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>"
}'| Mandrill | Emailit |
|---|---|
key dans le corps de la requête |
En-tête Authorization: Bearer secret_… |
message.from_email et from_name |
from: "Name <email>" |
message.to[] avec type to, cc ou bcc |
to, cc, bcc, 50 adresses au maximum pour chacun |
message.headers["Reply-To"] |
reply_to |
message.subject, html, text |
subject, html, text |
message.headers |
headers |
message.attachments[] avec type, name, content |
attachments[] avec content_type, filename, content |
message.images[] pour les images intégrées |
attachments[] avec un content_id, référencé sous la forme cid: dans le HTML |
message.metadata, message.tags |
meta, un objet de valeurs de type chaîne, renvoyé dans les événements webhook |
message.track_opens, track_clicks |
tracking: { "loads": true, "clicks": true } |
message.global_merge_vars |
variables |
message.merge_vars (par destinataire) |
Une requête par destinataire, chacune avec ses propres variables |
message.subaccount |
Utilisez une clé API de l’espace de travail correspondant |
send_at |
scheduled_at (ISO 8601 ou anglais courant) |
async |
Inutile. Emailit met chaque e-mail en file d’attente pour la livraison et répond sans attendre celle-ci. |
POST /messages/send-template avec template_name |
Le même POST /v2/emails avec template (un alias ou un ID) et variables |
Réponse : un tableau avec email, status et _id pour chaque destinataire |
200 avec id (em_…), status: "accepted" et, pour plusieurs destinataires, ids avec un ID par destinataire |
Mandrill signale les problèmes par destinataire dans la réponse, avec des statuts comme rejected ou invalid. Emailit valide l’ensemble de la requête et renvoie une erreur HTTP pour les données invalides. Les destinataires qui font l’objet d’un blocage recipient sont acceptés, puis reçoivent le statut suppressed. Ajoutez un en-tête Idempotency-Key pour sécuriser les relances. Consultez Envoyer un e-mail.
Changer les paramètres SMTP
| Paramètre | Mandrill | Emailit |
|---|---|---|
| Hôte | smtp.mandrillapp.com |
smtp.emailit.com |
| Port | 587, 2525 ou 25 (STARTTLS), 465 (TLS) |
587, 2587, 2525 ou 25 (STARTTLS), 465 (TLS) |
| Nom d’utilisateur | N’importe quelle valeur | emailit |
| Mot de passe | Une clé API Mandrill | Votre clé API Emailit |
Emailit ne lit pas les en-têtes X-MC-* comme X-MC-Template, X-MC-MergeVars, X-MC-Tags, X-MC-Metadata ou X-MC-Track. Supprimez-les. Réglez le suivi au niveau du domaine, et utilisez l’API quand vous avez besoin de modèles ou de métadonnées. Consultez Paramètres SMTP.
Faire correspondre les événements webhook
| Événement Mandrill | Événement Emailit |
|---|---|
send |
email.accepted (API uniquement) |
delivered |
email.delivered |
deferral |
email.attempted |
hard_bounce |
email.bounced |
soft_bounce |
email.attempted pendant qu’Emailit réessaie, puis email.bounced si toutes les nouvelles tentatives échouent |
open |
email.loaded |
click |
email.clicked |
spam |
email.complained |
unsub |
email.unsubscribed, pour les e-mails de campagne uniquement |
reject |
email.suppressed quand l’adresse a un blocage de type recipient. Les autres motifs de rejet, comme unsigned, sont des erreurs d’API dans Emailit. |
| Événements de synchronisation de la rejection denylist | suppression.created, suppression.deleted, pour les blocages que vous ajoutez ou supprimez |
inbound |
email.received, puis récupérez le contenu avec GET /emails/{id} |
Le format des requêtes change :
- Mandrill envoie (POST) un champ de formulaire,
mandrill_events, qui contient un tableau JSON de 1 000 événements au maximum. Emailit envoie le tableau JSON comme corps de la requête, avec 100 événements au maximum. - Le nom de l’événement se trouve dans
type, et l’e-mail dansdata.object. Utilisezdata.object.id, l’IDem_de la réponse d’envoi, au lieu de_id, etdata.object.toau lieu demsg.email. Vos valeursmetase 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. - Mandrill signe l’URL et les champs du formulaire avec HMAC-SHA1, encodé en base64, dans
X-Mandrill-Signature. Emailit signe<timestamp>.<raw body>avec HMAC-SHA256 : vérifiezX-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 l’intégralité de la liste de rejet avec Export Full Denylist sur la page Rejection Denylist de Mandrill, ou avec l’appel API
/exports/rejects./rejects/listrenvoie 1 000 entrées au maximum : ne l’utilisez donc pas pour cela. L’export est un fichier ZIP contenantrejects.csv, et couvre tous les sous-comptes. -
Constituez un seul CSV avec les colonnes
email,type,reason. Ignorez les entrées déjà expirées, et utilisez la colonnereasonpour choisir le type :Motif Mandrill Type Emailit hard-bounce,spam,customrecipientunsubunsubscribe, qui arrête les campagnes mais laisse passer les e-mails transactionnels. Utilisezrecipientpour bloquer tous les e-mails, comme le faisait Mandrill.soft-bounceLaissez-les de côté. Ces entrées expirent au bout d’un jour. email,type,reason old-address@example.com,recipient,mandrill hard-bounce angry@example.com,recipient,mandrill spamLe type
recipientbloque les envois par l’API, par SMTP et par les campagnes. Si vous utilisiez des sous-comptes, découpez le fichier selon sa colonne de sous-compte et importez chaque partie dans l’espace de travail correspondant. -
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.
La rejection allowlist de Mandrill n’a pas d’équivalent. Consultez Gérer les adresses bloquées.
Transférer les modèles
Récupérez le code de vos modèles depuis Mandrill : un seul appel /templates/list renvoie tous les modèles avec leur slug et leur HTML publié dans publish_code. Importez ensuite chacun d’eux dans Email MarketingTemplates ou créez-le avec l’API des modèles. Utilisez le slug Mandrill comme alias s’il respecte le format des alias : lettres minuscules, chiffres, - et _.
Dans les modèles qui utilisaient des zones mc:edit remplies par template_content, ces zones doivent devenir des variables. Les noms des variables de fusion Mandrill ne sont pas sensibles à la casse, mais ceux de Temple le sont : {{FNAME}} ne correspond qu’à une variable nommée FNAME. Convertissez les balises de fusion en Temple :
| Mandrill | Emailit (Temple) |
|---|---|
*|FNAME|* (langage de fusion Mailchimp) |
{{FNAME}}, ou renommez-la en {{first_name}} |
{{fname}} (langage de fusion Handlebars) |
{{fname}} |
*|IF:FNAME|*…*|ELSE:|*…*|END:IF|* |
{{#if FNAME}}…{{else}}…{{/if}} |
*|IF:PLAN=pro|*, ou une comparaison dans un {{#if}} Handlebars |
Non pris en charge. Transmettez un booléen comme is_pro et utilisez {{#if is_pro}}. |
*|DATE:d/m/y|*, *|CURRENT_YEAR|*, des helpers comme {{upper name}} |
Non pris en charge. Formatez la valeur dans votre code et transmettez-la. |
*|UNSUB:https://…|*, {{unsub "…"}} |
Votre propre lien de désinscription. Voir Désinscriptions. |
{{#if plan}}…{{else}}…{{/if}} |
Identique |
{{#each items}}…{{/each}} |
Non pris en charge. Générez la liste dans votre code et transmettez-la comme une seule variable. |
<div mc:edit="body">…</div> avec template_content |
{{body}}, transmis dans variables |
global_merge_vars |
variables |
Temple n’échappe jamais le HTML : échappez les saisies des utilisateurs avant de les transmettre. Une valeur manquante donne une chaîne vide, sauf si vous ajoutez une valeur par défaut, comme {{name|"there"}}. Consultez Temple.
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 les CNAME mte1._domainkey et mte2._domainkey de Mandrill ni avec son enregistrement TXT mandrill_verify. Conservez votre enregistrement DMARC. Consultez Enregistrements DNS.
Après la bascule, supprimez les enregistrements DKIM et de vérification de Mandrill, les éventuels CNAME de suivi ou de return-path personnalisés, et include:spf.mandrillapp.com si votre enregistrement SPF le contient. Si vous recevez des e-mails avec les routes de réception de Mandrill, déplacez-les d’abord vers un sous-domaine de réception Emailit.
É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