# En-têtes et métadonnées

> Ajoutez des en-têtes personnalisés et List-Unsubscribe à vos envois par l’API, découvrez les en-têtes qu’Emailit ajoute ou réécrit, et joignez des métadonnées renvoyées dans les webhooks.

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 :

```json
{
  "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

| En-tête | Ce que fait Emailit |
| --- | --- |
| `Message-ID` | Le définit à `<token@your-domain>`, la même valeur que `message_id` dans la réponse d’envoi. Un `Message-ID` que vous fournissez est remplacé. |
| `Date` | Le définit lorsqu’Emailit traite le message pour la première fois en vue de sa livraison. |
| `Subject` | Écrit l’objet final et encode les caractères non ASCII. |
| `Return-Path` | Définit une adresse de rebond sur votre sous-domaine de return-path, `emailit.<your-domain>`, pour que les rebonds reviennent à Emailit et que SPF soit aligné. |
| `DKIM-Signature` | Signe le message avec la clé DKIM de votre domaine. Une seconde signature pour `emailitmail.com` peut être ajoutée pour les boucles de rétroaction (feedback loops) sur les plaintes. |
| `Received` | Ajoute des en-têtes de trace pour l’API et le serveur de messagerie d’Emailit. |
| `X-Emailit-ID` | Ajoute le jeton de l’e-mail. |
| `Feedback-ID` | Ajoute un identifiant que les fournisseurs de messagerie utilisent dans les rapports de plainte. |
| `X-Emailit-Meta` | Ajoute vos valeurs `meta`, encodées en base64, quand vous envoyez `meta`. |
| `X-Emailit-Tracking` | Ajoute les paramètres demandés quand vous activez le suivi avec `tracking`. |
| `Bcc` | Le supprime, pour que les destinataires en copie cachée restent invisibles. |
| `Reply-To` | Le supprime quand il indique la même adresse que From. |
| `Content-Disposition` | Le supprime au niveau supérieur du message. Les parties des pièces jointes conservent le leur. |

Le [relais SMTP](/fr/docs/smtp/headers/) 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](/fr/docs/campaigns/) 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 :

```json
{
  "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 ?](/fr/docs/kb/gmail-yahoo-bulk-sender-requirements/).

Quand une personne se désinscrit, cessez de lui envoyer des e-mails. Vous pouvez l’ajouter à votre [liste d’adresses bloquées](/fr/docs/suppressions/) 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.

```json
{
  "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](/fr/docs/api-reference/emails/get/), [Récupérer les métadonnées](/fr/docs/api-reference/emails/meta/) et [Lister les e-mails](/fr/docs/api-reference/emails/list/).
- 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é) :

```json
[
  {
    "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](/fr/docs/email-api/retry-and-forward/) un e-mail conserve ses métadonnées. Le transfert crée un nouvel e-mail sans elles.

> **Les métadonnées voyagent avec le message:** Emailit écrit aussi `meta` dans le message sous la forme de l’en-tête `X-Emailit-Meta` encodé en base64 : toute personne qui consulte le message brut peut donc le décoder. Ne mettez ni secrets, ni jetons, ni données personnelles sensibles dans `meta`.

## 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](/fr/docs/api-reference/emails/get/).
- **Filtrez la liste.** [Lister les e-mails](/fr/docs/api-reference/emails/list/) filtre sur `to`, `from`, `subject`, `status`, `created_at`, `updated_at`, `spam_score`, `api_key_id` et `sending_domain_id`. Consultez [Filtrage et tri](/fr/docs/api-reference/filtering/).
- **Utilisez des clés API distinctes.** Donnez à chaque application ou fonctionnalité sa propre [clé API](/fr/docs/developers/api-keys/), 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](/fr/docs/email-api/send-email/)
- [En-têtes SMTP](/fr/docs/smtp/headers/)
- [Types d’événements webhook](/fr/docs/webhooks/event-types/)
- [Dictionnaire des en-têtes d’e-mail](/fr/docs/dictionary/email-headers/)

---
Source: https://emailit.com/fr/docs/email-api/headers-and-metadata/