Guide
Migrer depuis Elastic Email
Passez d’Elastic Email à Emailit. Faites correspondre les appels aux API v4 et v2, les identifiants SMTP et les notifications, convertissez les champs de fusion, et transférez adresses bloquées, contacts et campagnes.
Ce guide fait correspondre les concepts, les appels API, les notifications, les adresses bloquées, les modèles et les contacts d’Elastic 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.
Concepts
| Elastic Email | Emailit |
|---|---|
| Compte et sous-comptes | Compte et espaces de travail. Chaque espace de travail a ses propres domaines, clés, membres et crédits. |
| Clés API avec niveaux d’accès | Clés API : Full Access, ou Sending Only, éventuellement restreinte à un domaine |
| Identifiants SMTP | Votre clé API, utilisée comme mot de passe SMTP |
| Domaines vérifiés et adresses d’expéditeur vérifiées | Domaines d’envoi. Les adresses d’expéditeur individuelles ne sont pas disponibles. |
| Canaux et valeurs de postback | meta |
| Modèles, désignés par leur nom | Modèles avec un alias et des versions |
| Champs de fusion et scripts de modèle | Temple : variables, valeurs par défaut et conditions |
| Notifications web HTTP | Webhooks |
| Routes entrantes (inbound routes) | E-mails entrants |
| Adresses bloquées et statuts de contact qui bloquent l’envoi | Adresses bloquées |
| Contacts et listes | Contacts et listes de contacts |
| Segments | Choisissez et excluez des listes de contacts dans chaque campagne. Les segments sont en alpha et réservés à l’équipe Emailit. |
| Campagnes et automatisations | Campagnes et automatisations (bêta) |
| Formulaires | Formulaires (accès anticipé), ou l’URL d’inscription d’une liste de contacts |
| Vérification d’e-mails | Vérification d’e-mails |
| IP privées et pools d’IP | IP dédiées sur demande |
Elastic Email ajoute un lien de désinscription à chaque e-mail, y compris aux envois par l’API et par SMTP. Emailit n’ajoute les en-têtes List-Unsubscribe qu’aux campagnes et aux e-mails marketing des automatisations, et vous ajoutez vous-même le lien visible avec {{unsubscribe_url}}. Si vous envoyez des newsletters ou d’autres e-mails en masse via l’API ou SMTP, ajoutez votre propre lien et vos propres en-têtes List-Unsubscribe. Consultez En-têtes et métadonnées.
Mettre à jour vos appels API
Le POST /v4/emails/transactional d’Elastic Email devient POST /v2/emails. Le corps est plat, les noms de champs sont en minuscules, et la clé passe dans un en-tête Authorization :
curl https://api.elasticemail.com/v4/emails/transactional \
-H "X-ElasticEmail-ApiKey: $ELASTICEMAIL_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"Recipients": { "To": ["ada@example.com"] },
"Content": {
"From": "Acme <hello@acme.com>",
"Subject": "Your receipt",
"Body": [
{ "ContentType": "HTML", "Content": "<p>Thanks for your order.</p>" },
{ "ContentType": "PlainText", "Content": "Thanks for your order." }
]
}
}'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>"
}'| Elastic Email (API v4) | Emailit |
|---|---|
En-tête X-ElasticEmail-ApiKey |
Authorization: Bearer secret_… |
Content.From |
from |
Recipients.To, CC, BCC |
to, cc, bcc, 50 adresses au maximum pour chacun |
Content.ReplyTo |
reply_to |
Content.Subject |
subject |
Content.Body[] avec ContentType HTML et PlainText |
html et text |
Content.Headers |
headers |
Content.Attachments[] avec BinaryContent, Name, ContentType |
attachments[] avec content, filename, content_type |
Content.AttachFiles (fichiers chargés au préalable) |
attachments[] avec une url qu’Emailit télécharge |
Content.TemplateName |
template, un alias ou un ID de modèle |
Content.Merge |
variables |
Options.ChannelName, Content.Postback |
meta, renvoyé dans les événements webhook |
Options.TrackOpens, Options.TrackClicks |
tracking: { "loads": true, "clicks": true } |
Options.TimeOffset (en minutes) |
scheduled_at (ISO 8601 ou anglais courant) |
Options.PoolName |
Inutile. Une IP dédiée envoie tous les e-mails de son espace de travail. |
Content.Utm |
Ajoutez des paramètres UTM à vos liens. Les campagnes les ajoutent pour vous. |
POST /v4/emails avec Recipients[].Fields (fusion en masse) |
Une requête par destinataire, chacune avec ses propres variables |
En-tête Idempotency-Key |
En-tête Idempotency-Key, conservé 24 heures |
Réponse avec TransactionID et MessageID |
200 avec id (em_…), status: "accepted" et, pour plusieurs destinataires, ids avec un ID par destinataire |
Si vous utilisez encore l’API v2 (/v2/email/send avec un paramètre apikey), faites correspondre ses champs de formulaire de la même façon : from et fromName deviennent from, bodyHtml et bodyText deviennent html et text, les champs merge_* deviennent variables, et template devient template. En v2, chaque adresse de to reçoit un message distinct, comme en copie cachée (Cci). Dans Emailit, les destinataires de to se voient les uns les autres dans l’en-tête To : envoyez donc une requête par destinataire pour les garder séparés. Consultez Envoyer un e-mail.
Changer les paramètres SMTP
| Paramètre | Elastic Email | Emailit |
|---|---|---|
| Hôte | smtp.elasticemail.com |
smtp.emailit.com |
| Port | 2525, 587 ou 25 (STARTTLS), 465 (TLS) |
587, 2587, 2525 ou 25 (STARTTLS), 465 (TLS) |
| Nom d’utilisateur | Le nom de l’identifiant SMTP, une adresse e-mail | emailit |
| Mot de passe | Le jeton de l’identifiant SMTP | Votre clé API Emailit |
Emailit ne lit pas les en-têtes de contrôle d’Elastic Email, comme X-ElasticEmail-Channel, X-ElasticEmail-Postback, IsTransactional, trackopens ou trackclicks. Supprimez-les et réglez plutôt le suivi au niveau du domaine. Consultez Paramètres SMTP.
Faire correspondre les événements webhook
| Notification Elastic Email | Événement Emailit |
|---|---|
Sent (le serveur du destinataire a accepté le message) |
email.delivered |
Opened |
email.loaded |
Clicked |
email.clicked |
Error |
email.bounced pour les échecs définitifs. Les échecs temporaires envoient email.attempted pendant qu’Emailit réessaie. |
AbuseReport |
email.complained |
Unsubscribed |
email.unsubscribed, pour les e-mails de campagne uniquement |
| Route entrante qui notifie une URL | email.received, puis récupérez le contenu avec GET /emails/{id} |
Emailit envoie aussi email.accepted quand l’API accepte un e-mail, et email.suppressed quand un blocage de type recipient bloque une adresse. Consultez Types d’événements.
Le format des requêtes change :
- Elastic Email envoie un événement par requête, dans la chaîne de requête ou sous forme d’objet JSON plat. Emailit envoie un tableau JSON de 100 événements au maximum : parcourez donc le corps avec une boucle.
- Le nom de l’événement passe de
statusàtype, et l’e-mail se trouve dansdata.object. Utilisezdata.object.id, l’IDem_de la réponse d’envoi, au lieu demessageid, etdata.object.toau lieu deto. Vos valeursmeta, qui remplacentchanneletpostback, 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. - Emailit signe chaque requête. Vérifiez
X-Emailit-Signature, le HMAC-SHA256 en hexadécimal de<timestamp>.<raw body>, à l’aide deX-Emailit-Timestampet de votre secretwhsec_. La signature facultative d’Elastic Email utilise aussi des secretswhsec_, mais elle signe une chaîne différente : mettez donc à jour votre code de vérification. 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 les adresses qu’Elastic Email bloque, depuis Suppressions dans le tableau de bord ou avec l’API (
/v4/suppressions/bounces,/complaintset/unsubscribes). -
Constituez un seul CSV avec les colonnes
email,type,reason:Statut Elastic Email Type Emailit Invalid ( Bounced)recipientComplaint ( Abuse)recipientUnsubscribed unsubscribe, qui arrête les campagnes mais laisse passer les e-mails transactionnels. Utilisezrecipientpour bloquer tous les e-mails.email,type,reason old-address@example.com,recipient,elastic email bounced left@example.com,unsubscribe,elastic email unsubscribed -
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.
Consultez Gérer les adresses bloquées.
Transférer les contacts et les campagnes
Exportez vos contacts depuis Contacts (sélectionnez-les, puis More actions > Export) ou avec POST /v4/contacts/export, et exportez chaque liste à laquelle vous envoyez des campagnes. Transférez-les ensuite selon leur statut :
| Statut Elastic Email | Destination |
|---|---|
| Engaged, Active | Importez-les dans la liste de contacts correspondante dans Email MarketingContacts avec Import. |
| Transactional | Laissez-les en dehors des listes de contacts. Ils ne se sont jamais abonnés à vos e-mails marketing. |
| Invalid, Complaint, Unsubscribed | La liste d’adresses bloquées, comme ci-dessus. |
| Inactive, Stale, Not Confirmed | Laissez-les de côté. |
Créez des champs personnalisés pour vos champs de contact avant l’import, et découpez les fichiers en parties de 2 500 lignes au maximum. L’import ajoute toutes les personnes du fichier comme abonnées : n’importez donc que les personnes qui doivent recevoir vos campagnes. Consultez Importer et exporter des contacts.
Recréez vos campagnes et vos automatisations dans Email MarketingCampaigns et Automations, à partir de vos modèles importés.
Transférer les modèles
Copiez le HTML de chaque modèle avec Edit as HTML dans Elastic Email, ou récupérez-le avec GET /v4/templates/{name}, qui le renvoie dans Body. Importez-le dans Email MarketingTemplates ou créez-le avec l’API des modèles, et utilisez le nom du modèle comme alias s’il respecte le format des alias : lettres minuscules, chiffres, - et _.
Les champs de fusion d’Elastic Email utilisent des accolades simples, et Temple des doubles accolades. Les champs à accolades simples laissés dans un modèle sont envoyés en texte brut, alors convertissez-les tous :
| Elastic Email | Emailit (Temple) |
|---|---|
{firstname}, {lastname}, {email} |
{{first_name}}, {{last_name}}, {{email}} dans les campagnes. Dans les envois par l’API, les noms que vous transmettez dans variables. |
{firstname:friend} |
{{first_name|"friend"}} |
{company} ou un autre champ personnalisé |
{{cf.company}} dans les campagnes |
{unsubscribe} |
{{unsubscribe_url}} dans les campagnes |
{contactprofile} |
{{manage_subscriptions_url}} dans les campagnes |
{view} |
{{webview_url}} dans les campagnes |
{accountaddress} et les autres champs du compte |
Écrivez-les directement dans le modèle, ou conservez-les dans des valeurs globales |
Scripts de modèle dans {{ … }} |
Non pris en charge. Calculez les valeurs dans votre code et utilisez {{#if}} pour le contenu conditionnel. |
Consultez Balises de fusion et 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 l’enregistrement DKIM api._domainkey d’Elastic Email, ni avec son CNAME tracking ou un domaine de rebond personnalisé. Conservez votre enregistrement DMARC. Consultez Enregistrements DNS.
Après la bascule, supprimez les enregistrements DKIM et de suivi d’Elastic Email, et retirez include:_spf.elasticemail.com de votre enregistrement SPF. Si vous recevez des e-mails avec les routes entrantes d’Elastic Email, déplacez-les d’abord vers un sous-domaine de réception Emailit. Emailit reçoit sur un sous-domaine, comme inbound.acme.com : les adresses de réception changent donc.
É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