En-têtes et métadonnées

Cette page présente deux façons d’ajouter vos propres informations à un e-mail envoyé avec l’API e-mail : headers, qui font partie du message que reçoit le destinataire, et meta, qu’Emailit enregistre avec l’e-mail et renvoie dans l’API et dans les webhooks. Elle liste aussi les en-têtes qu’Emailit ajoute, réécrit ou supprime.

Ajouter des en-têtes personnalisés

Transmettez headers sous la forme d’un objet associant des noms d’en-têtes à des valeurs de type chaîne :

{
  "from": "Acme <orders@acme.com>",
  "to": "ada@example.com",
  "subject": "Receipt for order 1042",
  "text": "Thanks for your order.",
  "headers": {
    "X-Entity-Ref-ID": "order-1042",
    "X-Acme-Account": "881"
  }
}

• Pour From, To, Cc, Bcc, Reply-To et Subject, utilisez les champs de la requête, pas headers.
• Ne définissez pas d’en-têtes dont le nom commence par X-Emailit-. Emailit les utilise en interne. Par exemple, un message qui contient déjà X-Emailit-ID est considéré comme traité : Emailit ne réécrit pas ses en-têtes et ne le signe pas avec DKIM.
• Les en-têtes qu’Emailit définit lui-même, comme Message-ID et Date, sont remplacés même si vous les envoyez. Consultez la section suivante.

En-têtes qu’Emailit ajoute ou modifie

Le relais SMTP applique la même réécriture aux messages que vous soumettez via SMTP.

Ajouter List-Unsubscribe aux envois en masse

Les fournisseurs de messagerie comme Gmail et Yahoo attendent une option de désinscription en un clic dans les e-mails promotionnels et les autres envois en masse. Les campagnes en ajoutent une automatiquement. Pour les newsletters ou les récapitulatifs que vous envoyez via l’API, ajoutez vous-même les deux en-têtes :

{
  "from": "Acme <news@acme.com>",
  "to": "ada@example.com",
  "subject": "Acme weekly digest",
  "html": "<p>This week at Acme…</p>",
  "headers": {
    "List-Unsubscribe": "<https://acme.com/unsubscribe?u=881&l=digest>, <mailto:unsubscribe@acme.com?subject=unsubscribe-881>",
    "List-Unsubscribe-Post": "List-Unsubscribe=One-Click"
  }
}

• L’URL https doit accepter une requête POST avec le corps List-Unsubscribe=One-Click et désinscrire la personne sans lui demander de confirmation (RFC 8058).
• Rendez chaque URL propre au destinataire, pour que votre endpoint sache qui désinscrire.
• Emailit inclut List-Unsubscribe et List-Unsubscribe-Post dans la signature DKIM, ce que les fournisseurs exigent pour la désinscription en un clic.

Pour les autres exigences, consultez Comment respecter les exigences de Gmail et Yahoo pour les expéditeurs en masse ?.

Quand une personne se désinscrit, cessez de lui envoyer des e-mails. Vous pouvez l’ajouter à votre liste d’adresses bloquées pour qu’Emailit bloque les envois futurs.

Joindre des métadonnées

meta est un objet de clés et de valeurs de type chaîne qu’Emailit enregistre avec chaque e-mail. Utilisez-le pour relier un e-mail aux enregistrements de votre propre système.

{
  "from": "Acme <orders@acme.com>",
  "to": "ada@example.com",
  "subject": "Receipt for order 1042",
  "text": "Thanks for your order.",
  "meta": {
    "order_id": "1042",
    "customer_id": "cus_881",
    "kind": "receipt"
  }
}

Convertissez les nombres et les booléens en chaînes avant de les envoyer. Emailit renvoie meta :

• Dans Récupérer un e-mail, Récupérer les métadonnées et Lister les e-mails.
• Dans les événements webhook de l’e-mail : sous data.object.meta pour email.accepted, email.scheduled, email.canceled et les événements de livraison, et sous data.object.email.meta pour email.loaded et email.clicked.

Un événement de livraison avec des métadonnées ressemble à ceci (abrégé) :

[
  {
    "type": "email.delivered",
    "data": {
      "object": {
        "id": "em_33VtK8mRq1xZp7LwN4cY2bHsDfa",
        "object": "email",
        "to": "ada@example.com",
        "subject": "Receipt for order 1042",
        "status": "delivered",
        "meta": { "order_id": "1042", "customer_id": "cus_881", "kind": "receipt" }
      }
    }
  }
]

Relancer un e-mail conserve ses métadonnées. Le transfert crée un nouvel e-mail sans elles.

Retrouver des e-mails plus tard

Vous ne pouvez pas rechercher ni filtrer les e-mails par meta. Pour retrouver un e-mail :

• Conservez les ID. Enregistrez l’id, ou l’objet ids s’il y a plusieurs destinataires, à côté de votre propre enregistrement, et retrouvez l’e-mail avec Récupérer un e-mail.
• Filtrez la liste. Lister les e-mails filtre sur to, from, subject, status, created_at, updated_at, spam_score, api_key_id et sending_domain_id. Consultez Filtrage et tri.
• Utilisez des clés API distinctes. Donnez à chaque application ou fonctionnalité sa propre clé API, puis filtrez par api_key_id, ou par API key dans Email API›Emails.
• Associez les événements webhook. Lisez meta dans chaque événement pour l’associer au bon enregistrement dès son arrivée.

Voir aussi

• Envoyer un e-mail
• En-têtes SMTP
• Types d’événements webhook
• Dictionnaire des en-têtes d’e-mail