Guide
Migrer depuis Mailtrap
Passez de Mailtrap Email Sending à Emailit. Faites correspondre les flux, les jetons et les sous-comptes, convertissez les appels API et les modèles Handlebars, changez les paramètres SMTP, et transférez webhooks, adresses bloquées et contacts.
Ce guide fait correspondre les concepts, les appels API, les webhooks, les adresses bloquées, les modèles et les contacts de Mailtrap Email Sending à 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.
Concepts
| Mailtrap | Emailit |
|---|---|
| Organisation et sous-comptes | Compte et espaces de travail. Chaque espace de travail a ses propres domaines, clés, membres et crédits. |
| Domaines d’envoi | Domaines d’envoi |
| Flux transactionnel (transactional stream) | L’API e-mail et le relais SMTP |
| Flux bulk (bulk stream) | Des campagnes, ou l’API avec vos propres en-têtes List-Unsubscribe |
| Jetons d’API avec droits par ressource | Clés API : Full Access, ou Sending Only, éventuellement restreinte à un domaine |
| Domaine de démonstration | Les nouveaux espaces de travail sont en mode bac à sable et peuvent envoyer aux membres de l’espace de travail depuis votre propre domaine vérifié. |
| Email Sandbox (tests) | Non disponible. Gardez l’Email Sandbox de Mailtrap pour vos tests, ou envoyez aux membres de l’espace de travail pendant le développement. |
| Modèles | Modèles avec un alias et des versions, dont le rendu est effectué avec Temple |
| Webhooks par flux | Webhooks par espace de travail |
| Adresses bloquées par domaine et par flux | Une seule liste d’adresses bloquées par espace de travail |
| Logs d’e-mails | Email APIEmails et Email APILogs |
category et custom_variables |
meta |
| Email Marketing : contacts, listes, campagnes, automatisations | Contacts, listes de contacts, campagnes et automatisations (bêta) |
| E-mails entrants | E-mails entrants |
Pour séparer la réputation transactionnelle et la réputation marketing, comme le font les deux flux de Mailtrap, envoyez-les depuis des domaines ou sous-domaines différents, par exemple mail.acme.com pour les reçus et news.acme.com pour les newsletters.
Mettre à jour vos appels API
Le POST /api/send de Mailtrap devient POST /v2/emails. Les deux reçoivent un jeton bearer et du JSON, mais les adresses d’Emailit sont de simples chaînes au lieu d’objets :
curl https://send.api.mailtrap.io/api/send \
-H "Authorization: Bearer $MAILTRAP_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"from": { "email": "hello@acme.com", "name": "Acme" },
"to": [{ "email": "ada@example.com" }],
"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>"
}'| Mailtrap | Emailit |
|---|---|
Authorization: Bearer <token> ou Api-Token: <token> |
Authorization: Bearer secret_… |
send.api.mailtrap.io et bulk.api.mailtrap.io |
Un seul hôte, api.emailit.com |
from: { email, name } |
from: "Name <email>" |
to[], cc[], bcc[] avec email et name |
to, cc, bcc sous forme de chaîne ou de tableau, 50 adresses au maximum pour chacun |
reply_to: { email, name } |
reply_to |
subject, text, html, headers |
Identiques |
attachments[] avec content, filename, type, disposition et content_id |
attachments[] avec content, filename, content_type et content_id, ou une url à la place de content |
category |
meta, par exemple meta: { "category": "password-reset" } |
custom_variables |
meta, renvoyé dans les événements webhook |
template_uuid et template_variables |
template (un alias ou un ID) et variables |
| Suivi réglé par domaine | Suivi réglé par domaine, ou par e-mail avec tracking: { "loads": true, "clicks": true } |
POST /api/batch (500 messages au maximum) |
Non disponible. Envoyez une requête par message. |
Réponse avec message_ids, un par destinataire |
200 avec id (em_…), status: "accepted" et, pour plusieurs destinataires, ids avec un ID par destinataire |
Emailit prend aussi en charge la programmation avec scheduled_at et les relances sûres avec un en-tête Idempotency-Key, ce que l’API d’envoi de Mailtrap ne propose pas. Consultez Envoyer un e-mail.
Changer les paramètres SMTP
| Paramètre | Mailtrap | Emailit |
|---|---|---|
| Hôte | live.smtp.mailtrap.io, ou bulk.smtp.mailtrap.io pour le flux bulk |
smtp.emailit.com |
| Port | 587, 2525 ou 25 (STARTTLS), 465 (TLS) |
587, 2587, 2525 ou 25 (STARTTLS), 465 (TLS) |
| Nom d’utilisateur | api |
emailit |
| Mot de passe | Votre jeton d’API Mailtrap | Votre clé API Emailit |
Emailit ne lit pas les en-têtes X-MT-Category ni X-MT-Custom-Variables. Supprimez-les et utilisez l’API quand vous avez besoin de métadonnées. Consultez Paramètres SMTP.
Faire correspondre les événements webhook
| Événement Mailtrap | Événement Emailit |
|---|---|
delivery |
email.delivered |
soft bounce |
email.attempted pendant qu’Emailit réessaie, puis email.bounced si toutes les nouvelles tentatives échouent |
bounce |
email.bounced |
reject |
email.suppressed quand l’adresse a un blocage de type recipient |
suspension |
email.held |
spam |
email.complained |
open |
email.loaded |
click |
email.clicked |
unsubscribe |
email.unsubscribed, pour les e-mails de campagne uniquement |
inbound.message_received |
email.received, puis récupérez le contenu avec GET /emails/{id} |
Emailit envoie aussi email.accepted quand l’API accepte un e-mail. Consultez Types d’événements.
Le format des requêtes change :
- Mailtrap envoie une liste
eventsde 500 événements au maximum, ou du JSON Lines. Emailit envoie comme corps de la requête un tableau JSON de 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 demessage_id, etdata.object.toau lieu deemail. Vos valeursmeta, qui remplacentcategoryetcustom_variables, 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. - L’en-tête
Mailtrap-Signaturede Mailtrap est un HMAC-SHA256 du corps brut. L’en-têteX-Emailit-Signatured’Emailit est un HMAC-SHA256 de<timestamp>.<raw body>, calculé avec votre secretwhsec_: lisez donc aussiX-Emailit-Timestamp. 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 vos adresses bloquées depuis Suppressions dans Mailtrap, ou parcourez les pages de
GET https://mailtrap.io/api/suppressions, qui renvoie 1 000 entrées au maximum par appel. -
Constituez un seul CSV avec les colonnes
email,type,reason:Type Mailtrap Type Emailit hard bounce,spam complaint,manual importrecipient, qui bloque les envois par l’API, par SMTP et par les campagnesunsubscriptionunsubscribe, qui arrête les campagnes mais laisse passer les e-mails transactionnels. Utilisezrecipientpour les désinscriptions du flux transactionnel.email,type,reason old-address@example.com,recipient,mailtrap hard bounce left@example.com,unsubscribe,mailtrap unsubscription -
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 : les adresses bloquées pour plusieurs domaines ou flux Mailtrap ne sont donc ajoutées qu’une fois.
Consultez Gérer les adresses bloquées.
Transférer les contacts
Si vous utilisez Mailtrap Email Marketing, exportez vos contacts depuis Contacts avec More Actions > Export, ou avec POST https://mailtrap.io/api/contacts/exports filtré sur subscription_status et list_id. Créez d’abord dans Emailit les champs personnalisés et les listes de contacts correspondants.
N’importez que les contacts abonnés, une liste de contacts à la fois, dans Email MarketingContacts avec Import. L’import ajoute toutes les personnes du fichier comme abonnées : ajoutez donc plutôt les contacts désinscrits à votre fichier d’adresses bloquées, avec le type unsubscribe. Découpez les fichiers en parties de 2 500 lignes au maximum. Consultez Importer et exporter des contacts.
Transférer les modèles
Récupérez le HTML de vos modèles avec GET https://mailtrap.io/api/email_templates, qui renvoie le body_html, le body_text et le subject de chaque modèle. Importez chacun d’eux dans Email MarketingTemplates ou créez-le avec l’API des modèles, et donnez-lui un alias, comme receipt.
Les modèles Mailtrap utilisent Handlebars. Temple couvre les usages courants :
| Mailtrap (Handlebars) | Emailit (Temple) |
|---|---|
{{name}}, {{user.name}} |
Identique |
{{{html_block}}} |
{{html_block}}. Temple n’échappe jamais le HTML : échappez vous-même les saisies des utilisateurs. |
{{#if plan}}…{{else}}…{{/if}} |
Identique |
{{#unless plan}}…{{/unless}} |
{{#if plan}}{{else}}…{{/if}} |
{{#if name}}{{name}}{{else}}Customer{{/if}} |
{{name|"Customer"}} |
{{#each items}}…{{/each}}, {{#with}} |
Non pris en charge. Générez la liste dans votre code et transmettez-la comme une seule variable. |
template_variables |
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 les enregistrements DKIM rwmt1._domainkey et rwmt2._domainkey de Mailtrap, ni avec son CNAME de vérification ou son CNAME de suivi mt-link. Conservez votre enregistrement DMARC. Consultez Enregistrements DNS.
Après la bascule, supprimez les enregistrements DKIM, de vérification et de suivi de Mailtrap, ainsi que include:_spf.mailtrap.io si votre enregistrement SPF le contient encore. La réception Mailtrap utilise l’enregistrement MX de votre domaine racine, et la réception Emailit un sous-domaine comme inbound.acme.com : déplacez donc les e-mails entrants et mettez à jour vos adresses de réception avant de modifier l’enregistrement MX. Consultez Configurer la réception.
É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