---
title: Réception
description: Recevez des e-mails sur votre propre domaine et lisez-les via l'API, les webhooks et le tableau de bord.
seo:
  title: API de réception d'emails
ai:
  exclude: true
---

La réception transforme un domaine que vous avez vérifié en un endroit qui accepte du courrier. Les messages entrants sont stockés chiffrés et vous parviennent via l'API, le webhook `email.received`, le tableau de bord (**Boîtes de réception → Tous les e-mails reçus**) et le [serveur MCP](/docs/fr/mcp).

Il y a deux façons de choisir les adresses qui acceptent du courrier : créez une [boîte de réception](/docs/fr/inboxes) pour une adresse, ou activez le **catch-all** pour accepter toutes les autres adresses du domaine.

> **Info**
>
> La réception est en bêta publique. Chaque message reçoit un score de spam, un niveau de confiance de l'expéditeur et une analyse antivirus. Un e-mail infecté est retenu ; tout le reste est stocké avec ces résultats, pour que votre code décide quoi en faire.

## Configuration

1. **Choisissez un nom qui ne reçoit pas encore de courrier**, par exemple `inbound.example.com`. L'enregistrement MX prend en charge toutes les adresses du nom sur lequel il est publié ; vos boîtes mail sur `example.com` restent donc chez votre fournisseur actuel.
2. **Ajoutez et vérifiez ce nom exact** sous **Domaines**, comme pour l'[envoi](/docs/fr/concepts/domains). Vérifier `example.com` ne couvre pas ses sous-domaines.
3. **Activez la réception** : ouvrez le domaine et activez **Activer la réception**, ou appelez l'API :

   ```sh
   curl -X PATCH "https://api.billionsend.com/domains/{id}" \
     -H "Authorization: Bearer bs_..." \
     -H "Content-Type: application/json" \
     -d '{ "capabilities": { "receiving": "enabled" } }'
   ```

   Un nom ne peut recevoir que dans une seule équipe ; un nom sur lequel une autre équipe reçoit déjà répond `409`.
4. **Publiez les deux enregistrements MX** affichés dans les enregistrements du domaine, chez votre fournisseur DNS :

   | Type | Nom | Valeur | Priorité |
   | --- | --- | --- | --- |
   | MX | `inbound.example.com` | `mx1.billionsend-dns.com` | `10` |
   | MX | `inbound.example.com` | `mx2.billionsend-dns.com` | `10` |

   Chacun est un serveur de messagerie distinct. Quand les deux sont publiés, un expéditeur qui trouve l'un d'eux hors service réessaie sur l'autre en quelques secondes ; publiez donc les deux avec la même priorité. Chaque ligne est vérifiée dès qu'aucun autre enregistrement MX de ce nom n'a un numéro de priorité plus bas.
5. **Choisissez les adresses** : [créez une boîte de réception](/docs/fr/inboxes) pour chaque adresse, ou activez **Catch-all** sur la page du domaine. Sans l'un ni l'autre, le domaine refuse tout le courrier.
6. **Envoyez un test** depuis n'importe quelle boîte mail. Il apparaît sous **Boîtes de réception → Tous les e-mails reçus** en quelques secondes.

Pour arrêter de recevoir, désactivez la réception (`"receiving": "disabled"`) et supprimez l'enregistrement MX. Les e-mails déjà stockés restent jusqu'à ce que la durée de conservation les supprime.

## Quelles adresses reçoivent

- L'adresse de chaque [boîte de réception](/docs/fr/inboxes) du domaine, et ses variantes avec `+tag` : `orders+4821@` arrive dans la boîte de réception de `orders@`.
- Avec le **catch-all** activé, toutes les autres adresses aussi : `support@`, `invoices@`, `reply+ticket-4821@`. Lisez `received_for` dans votre code pour savoir à quelle adresse un message est arrivé.

Avec le catch-all désactivé, toute autre adresse est refusée alors que le serveur de l'expéditeur est encore connecté (`550 5.1.1`) : l'expéditeur reçoit un rebond de son propre serveur et rien n'est stocké.

Le catch-all est désactivé par défaut et exige un forfait payant (Free répond `403 plan_limit_reached`). Les propriétaires, les administrateurs et les développeurs l'activent sur la page du domaine, ou avec `PATCH /domains/{id}` et `{ "receiving_catch_all": true }`.

- `received_for` liste les adresses de vos domaines auxquelles le message a réellement été remis, Cci compris. `to` et `cc` ne sont que ce que prétendent les en-têtes : routez donc sur `received_for`.
- Un message n'est stocké qu'une seule fois par équipe, quel que soit le nombre de vos adresses auxquelles il a été envoyé.
- Seul le nom exact reçoit : un e-mail adressé à `x@eu.inbound.example.com` est refusé, sauf si ce sous-domaine reçoit lui aussi.

## Filtrage et limites

**Paramètres → Réception** propose trois interrupteurs. Ils s'appliquent à tous les domaines de votre équipe et prennent effet dès le message suivant.

| Interrupteur | Activé | Désactivé |
| --- | --- | --- |
| Rejeter le spam au-dessus du score 5 (activé par défaut) | Un e-mail dont le score de spam est de 5 ou plus (sur une échelle de 0 à 10) est refusé avec `554 5.7.1` ; rien n'est stocké. | Le spam est stocké : dans le dossier `spam` d'une boîte de réception, simplement signalé sur une adresse catch-all. |
| Retirer les pièces jointes de plus de 10 MB (désactivé par défaut) | Chaque pièce jointe plus grande est remplacée par une courte note `<fichier>.removed.txt` indiquant ce qui a été retiré. | Les pièces jointes sont stockées telles qu'elles sont arrivées. |
| Conserver le .eml brut 30 jours (activé par défaut) | Le contenu reste pendant votre durée de conservation. | Le contenu (texte, HTML, en-têtes, message brut, pièces jointes) est supprimé après 1 jour. Les métadonnées et les webhooks ne changent pas. |

| Limite | Free | Starter, Pro, Scale |
| --- | --- | --- |
| Taille du message | 10 MB | 40 MB |
| Catch-all | Non | Oui |
| E-mails reçus | 100 par jour UTC | 2 fois le volume mensuel de votre forfait, chaque mois |
| Au-delà | Différé jusqu'à minuit UTC | Différé jusqu'au renouvellement de votre volume |
| Conservation | 30 jours | 30 jours |

- La taille compte le message stocké en entier, après retrait des pièces jointes. Le Base64 alourdit les pièces jointes d'environ un tiers : sur 40 MB, il tient donc à peu près 30 MB de fichiers. Un message plus grand est refusé avec `552 5.3.4`.
- Un e-mail reçu compte une fois par message et par équipe, dans sa propre limite. Il n'utilise jamais votre volume d'envoi, et l'envoi n'utilise jamais votre limite de réception.
- Quand la limite est atteinte, le serveur de l'expéditeur reçoit l'ordre de réessayer plus tard (`452 4.2.2`) et réessaie pendant plusieurs jours, couramment jusqu'à cinq : le message arrive donc dès qu'il y a de la place. Un e-mail encore différé quand le serveur de l'expéditeur abandonne est renvoyé à son expéditeur.
- Quand la conservation prend fin, `html`, `text`, `headers` et `raw` valent `null`, `attachments` est vide et les liens de téléchargement cessent de fonctionner. L'expéditeur, les destinataires et l'objet restent.

**Paramètres → Facturation et consommation** affiche les e-mails reçus et leur limite. Les boîtes de réception elles-mêmes sont gratuites.

## Lire les e-mails reçus

Utilisez `emails.receiving` dans les [SDK](/docs/fr/sdks), ou du HTTP brut. Ces points d'accès exigent une [clé API](/docs/fr/api-keys) à **accès complet** ; une clé réservée à l'envoi reçoit `403 restricted_api_key`. Une clé restreinte à un domaine ne lit que les e-mails de ce domaine, et une clé restreinte à une boîte de réception que ceux de cette boîte.

```ts
import { BillionSend } from "@billionsend/node";

const bs = new BillionSend(); // lit BILLIONSEND_API_KEY

const page = await bs.emails.receiving.list({ limit: 20 });
if (page.error) throw page.error;

const first = page.data.data[0];
const email = await bs.emails.receiving.get(first.id);
const files = await bs.emails.receiving.attachments.list(first.id);
```

| Appel | Renvoie |
| --- | --- |
| `GET /emails/receiving` | Les e-mails reçus, du plus récent au plus ancien, avec [la pagination que toutes les listes utilisent](/docs/fr/api-reference/basics). |
| `GET /emails/receiving/{id}` | Un e-mail avec son contenu, ses résultats d'authentification et un lien de téléchargement du message d'origine. |
| `GET /emails/receiving/{id}/attachments` | Ses pièces jointes, chacune avec un lien de téléchargement. |
| `GET /emails/receiving/{id}/attachments/{attachment_id}/text` | Le texte d'une pièce jointe PDF, Word ou Excel (extension BillionSend). |
| `DELETE /emails/receiving/{id}` | Efface l'e-mail immédiatement, avec ses pièces jointes et sa place dans les boîtes de réception. Exige une clé à accès complet non restreinte à une boîte de réception, et le rôle de propriétaire, d'administrateur ou de développeur dans le tableau de bord (**Supprimer maintenant**). |

La liste accepte `limit` (1 à 100, 20 par défaut), `inbox_id`, `to`, `from` (une adresse, ou un domaine avec ses sous-domaines), `subject_contains`, `since`, `unread` et `wait`. Les e-mails retenus sont exclus, sauf si vous passez `include_quarantined=true` ou `quarantined=true` (une clé à accès complet non restreinte à une boîte de réception).

Chaque e-mail porte aussi `inbox_id`, `thread_id`, `screening`, `spam_verdict`, `virus_verdict` et `extracted`.

### Attendre de nouveaux e-mails

`wait` (1 à 50 secondes) maintient la requête ouverte jusqu'à l'arrivée d'un e-mail correspondant, puis répond aussitôt ; à l'échéance, il répond par une liste vide. Il se combine avec les autres filtres : un agent peut ainsi attendre le prochain message d'un expéditeur vers une boîte de réception :

```sh
curl "https://api.billionsend.com/emails/receiving?inbox_id=7eeb9517-aed7-40d7-ad65-500be42ed147&from=example.org&wait=30" \
  -H "Authorization: Bearer bs_..."
```

- Sans `before` ni `since`, les e-mails des 60 dernières secondes comptent : un message arrivé juste avant l'appel n'est donc pas manqué.
- La réponse ajoute `held` : les messages correspondants retenus depuis, avec leur id et leur motif, pour que l'agent sache qu'il doit arrêter d'attendre et prévenir une personne.
- Une équipe peut avoir 20 attentes simultanées sur chaque processus de l'API ; la suivante répond `429 too_many_waits`.
- Une attente interroge la base de données à l'arrivée d'un e-mail (les mêmes événements que le [flux d'événements des boîtes de réception](/docs/fr/inboxes)), et non sur un minuteur.

### Résultats d'authentification

`authentication` indique SPF, DKIM et DMARC sous la forme `pass`, `fail`, `gray` (aucun verdict : pas d'enregistrement ni de signature, ou résultat neutre), `processing_failed` (la vérification n'a pas pu aboutir) ou `unknown`. `dmarc: "pass"` signifie que le domaine de `from` a autorisé le message ; toute autre valeur signifie que `from` peut être falsifié. Le niveau de [confiance de l'expéditeur](/docs/fr/agent-safety) est construit à partir de ces résultats.

### Spam, virus et confiance

- `spam_verdict` : `pass`, `gray` (`spam_score` de 25 à 49) ou `fail` (50 ou plus), d'après un score de 0 à 100 construit à partir de l'authentification, des en-têtes, des liens, des pièces jointes et du score du filtre antispam des serveurs de réception (le tableau de bord l'affiche sur une échelle de 0 à 10).
- `virus_verdict` : `pass`, `fail` (avec `virus_signature`), `processing_failed` (l'antivirus n'a pas pu répondre : le message est remis sans analyse, marqué comme suspect là où il n'est pas filtré) ou `null` quand aucune analyse n'a eu lieu. Un e-mail infecté est retenu : il ne déclenche aucun `email.received` tant qu'une personne ne l'a pas libéré dans le tableau de bord, et ses téléchargements répondent `410 email_blocked`, même après une libération.
- `screening.sender_trust` : dans quelle mesure l'expéditeur est établi. Voir [Sécurité des agents](/docs/fr/agent-safety).

### Contenu

- `html_format` : `data_uri` (par défaut) place les images en ligne dans le HTML ; `?html_format=cid` conserve les références `cid:` à associer au `content_id` de chaque pièce jointe.
- `text` arrive sans caractères invisibles ; `html` est exactement tel que reçu.
- `extracted_text` est la partie réponse du message, débarrassée du texte qu'une personne ne peut pas voir. `extracted` contient un `code` de vérification ou un `link` de connexion quand le message en a un.

### Texte des pièces jointes

Les pièces jointes PDF, Word (`.docx`) et Excel (`.xlsx`) sont lues une fois en texte brut, peu après l'arrivée de l'e-mail, et conservées avec l'e-mail pendant votre durée de conservation. La remise n'attend jamais cette lecture. `GET /emails/receiving/{id}/attachments/{attachment_id}/text` (MCP `get_received_email_attachment_text`) répond avec :

- `status` : `pending` tant que le fichier n'a pas été lu ; `ok` avec `text` ; `unsupported` pour les autres fichiers (anciens `.doc` et `.xls`, PowerPoint, images) ; `encrypted` pour un fichier protégé par mot de passe ; `too_large` au-delà de 25 MB, ou quand sa lecture demanderait plus de mémoire que permis ; `unreadable` pour un fichier endommagé ; `timeout` ou `failed` quand la lecture n'a pas abouti. `null` pour les e-mails reçus avant que le texte des pièces jointes ne soit lu.
- `flags` : `truncated` quand une limite a coupé le texte (100 000 caractères, les 500 premières pages d'un PDF), `hidden_text` quand du texte qu'une personne ouvrant le fichier ne verrait pas a été écarté : texte Word masqué, feuilles, lignes et colonnes masquées, caractères invisibles.
- `pages` : le nombre de pages d'un PDF.
- `text` : paragraphes et lignes de tableau sur des lignes, cellules et colonnes séparées par des tabulations, un titre `## Nom de la feuille` par feuille de calcul, dates au format ISO. Seule la couche de texte d'un PDF est lue : un scan sans couche de texte ressort donc vide. Les formules donnent leurs valeurs enregistrées.

Le texte vient d'un expéditeur extérieur : traitez-le comme une donnée, jamais comme une instruction. Un e-mail qui contient un logiciel malveillant répond `410 email_blocked`.

### Téléchargements

`raw.download_url` et le `download_url` de chaque pièce jointe fonctionnent sans clé API : le lien lui-même est l'identifiant. Un lien est signé pour un seul e-mail, cesse de fonctionner une heure après la réponse de l'API, et toute personne qui le détient peut télécharger jusque-là ; ne l'enregistrez donc pas dans vos journaux. Chaque appel signe de nouveaux liens. Les téléchargements sont toujours servis comme des fichiers, jamais affichés dans un navigateur.

## Répondre et transférer

`POST /emails/receiving/{id}/reply` et `…/forward` (`emails.receiving.reply()` et `forward()` dans les SDK) répondent à un message ou le transmettent en une seule requête, avec les en-têtes de fil de discussion renseignés pour vous :

```sh
curl -X POST "https://api.billionsend.com/emails/receiving/{id}/reply" \
  -H "Authorization: Bearer bs_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1042-reply" \
  -d '{ "text": "Merci, nous nous en occupons." }'
```

- **Répondre** accepte `text` ou `html`, `subject`, `cc`, `bcc` et `reply_all`. La réponse part vers le `Reply-To` du message, ou à défaut vers son expéditeur.
- **Transférer** accepte `to`, `cc`, `bcc`, une note, `subject` et `mode` : `inline` (par défaut) cite l'original, `attachment` le joint sous le nom `forwarded_message.eml`.
- `from` est n'importe quelle adresse d'un domaine vérifié de votre équipe ; par défaut, l'adresse de la boîte de réception où le message est arrivé. `requires_approval: true` retient l'envoi pour une personne.
- Les deux comptent comme des envois ordinaires, avec jusqu'à 10 MiB de pièces jointes.

Ils répondent `200` avec l'`id` et le `thread_id` de l'e-mail envoyé, ou `202` avec un brouillon quand les règles d'une boîte de réception retiennent l'envoi. Autres réponses : `403` (e-mail retenu ou infecté, règles d'une boîte de réception, clé limitée à une boîte de réception utilisée en dehors d'elle), `404`, `409` (`Idempotency-Key` réutilisée), `422` et `429 inbox_send_cap_reached`. Voir [Boîtes de réception](/docs/fr/inboxes).

## Webhook

`email.received` se déclenche une fois pour chaque message stocké pour votre équipe, vers les points d'accès abonnés à cet événement ou à tous les événements. Il ne porte que des métadonnées (expéditeur, destinataires, objet, liste des pièces jointes) ; récupérez le contenu avec `GET /emails/receiving/{email_id}`. Un e-mail qu'une boîte de réception retient, ou un e-mail infecté, ne le déclenche qu'une fois remis ou libéré. Un point d'accès limité à certaines boîtes de réception (`inbox_ids`) ne le reçoit que pour les e-mails qui y sont remis. Les signatures, les nouvelles tentatives et le journal des envois fonctionnent comme pour tous les événements : voir [Webhooks](/docs/fr/concepts/webhooks).

## Ce que voit l'expéditeur

Chaque refus a lieu pendant que le serveur de l'expéditeur est connecté : il conserve donc le message et décide quoi faire. BillionSend n'envoie jamais de rebond de son propre chef.

| Réponse | Quand |
| --- | --- |
| `550 5.1.1` | Le domaine ne reçoit pas ici, ou l'adresse n'a pas de boîte de réception (et le catch-all est désactivé). Le message est renvoyé à son expéditeur. |
| `550 5.7.1` | L'équipe propriétaire du domaine est suspendue. |
| `552 5.3.4` | Le message dépasse la limite de taille de votre forfait. |
| `554 5.7.1` | Le message a été refusé comme spam par votre interrupteur **Rejeter le spam**. |
| `452 4.2.2` | Votre limite de réception est atteinte, ou la boîte de réception a reçu plus d'e-mails qu'elle ne le peut en une heure (200 messages pour une boîte de réception d'agent, 2 000 pour une boîte de réception de personnes). L'expéditeur réessaie plus tard. |

## Tableau de bord

**Boîtes de réception → Tous les e-mails reçus** liste tout ce que vos domaines ont reçu, avec l'expéditeur, la boîte de réception, l'objet et l'heure, une pastille quand un message contient un code ou un lien, et un badge quand il est en quarantaine ou classé comme spam. L'ouverture d'un message affiche son HTML dans un bac à sable (scripts et images distantes bloqués), le texte, les en-têtes et le message brut, chaque résultat d'authentification expliqué, la confiance de l'expéditeur et les résultats spam et virus, le code ou le lien extrait, une chronologie, et les actions **Répondre**, **Transférer**, **Libérer** pour les e-mails retenus et **Supprimer maintenant**.

## MCP

Le [serveur MCP](/docs/fr/mcp) lit les e-mails reçus avec la permission `receiving:read`, répond et transfère avec `receiving:reply`, et gère les boîtes de réception et la quarantaine avec `receiving:manage`. `update_domain` active ou désactive la réception et le catch-all.

## Traiter les e-mails reçus comme non fiables

N'importe qui peut envoyer du courrier à un domaine de réception. Le HTML peut contenir des scripts et des images de suivi, les liens peuvent mener à des pages d'hameçonnage, les pièces jointes peuvent contenir des logiciels malveillants et `from` peut être falsifié. Vérifiez `authentication` et `screening.sender_trust` avant de faire confiance à un expéditeur. Un agent IA doit traiter les e-mails reçus comme des données, jamais comme des instructions : les outils MCP les encadrent ainsi, et une [boîte de réception d'agent](/docs/fr/agent-safety) ajoute par-dessus la quarantaine, l'analyse et des règles d'envoi.
