---
title: Boîtes de réception
description: Des adresses e-mail qui gardent les messages en fils et répondent depuis la même adresse, pour un agent IA ou pour des personnes.
seo:
  title: Boîtes de réception pour agents IA
ai:
  exclude: true
---

Une boîte de réception est une adresse e-mail qui reçoit les messages en fils et envoie depuis la même adresse. Donnez-en une à un agent IA, qui la lit par l'API, par des webhooks ou par le [serveur MCP](/docs/fr/mcp), ou à des personnes, qui la lisent dans le tableau de bord. Une boîte est une adresse sur l'un de vos [domaines de réception](/docs/fr/receiving), ou une adresse sur le domaine partagé de BillionSend, qui n'a pas besoin de DNS.

Les [SDK](/docs/fr/sdks) couvrent chaque endpoint de boîte sous la forme `inboxes.*`, y compris les règles de sécurité, la quarantaine, les approbations et le flux d'événements en direct.

> **Info**
>
> Les boîtes de réception sont en bêta, sous **Boîtes de réception** dans le tableau de bord.

## Agent ou personnes

Chaque boîte a un `kind`, choisi à sa création et jamais modifié. Le type fixe les valeurs par défaut des paramètres de sécurité.

| Paramètre | Agent | Personnes |
| --- | --- | --- |
| `accept_from` | `verified` | `anyone` |
| `screening` | activé | désactivé |
| `extract_codes` | activé | activé |
| `send_policy` | `reply_only` | `open` (`reply_only` sur le domaine partagé) |
| `require_approval` | désactivé | désactivé |
| `private_codes` | activé | désactivé |
| `send_cap` | 200 (50 sur le domaine partagé) | aucun (50 sur le domaine partagé) |

- **`agent`** est la valeur par défaut quand `kind` est omis. Les e-mails d'expéditeurs dont le domaine ne se porte pas garant attendent en quarantaine, ceux des autres expéditeurs externes sont analysés contre l'injection de prompt, et l'agent répond dans les fils existants : une nouvelle conversation qu'il démarre devient un brouillon qui attend une personne. Voir [Sécurité des agents](/docs/fr/agent-safety).
- **`human`** est pour des personnes qui lisent dans le tableau de bord : les e-mails de tout le monde sont distribués (un échec d'authentification atterrit dans le dossier `spam`) et rien n'est analysé.

Un e-mail porteur d'un virus est mis en quarantaine dans toutes les boîtes.

## Créer une boîte de réception

Dans le tableau de bord, ouvrez **Boîtes de réception** et choisissez **Créer une boîte de réception**. Ou appelez l'API :

```sh
curl -X POST "https://api.billionsend.com/inboxes" \
  -H "Authorization: Bearer bs_..." \
  -H "Content-Type: application/json" \
  -d '{
    "email_address": "orders@inbound.example.com",
    "name": "Orders agent",
    "kind": "agent"
  }'
```

Avec le SDK Node.js :

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

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

const { data, error } = await bs.inboxes.create({
  email_address: "orders@inbound.example.com",
  name: "Orders agent",
  kind: "agent",
});
```

La réponse (`201`) est la boîte complète : `id`, `name`, `email_address`, `domain_id`, `kind`, `shared`, `expires_at`, `unread` (fils contenant un message non lu), `drafts`, `quarantined`, `pending_approval` et d'autres champs.

| Champ | Règles |
| --- | --- |
| `email_address` | Une adresse sur un domaine vérifié de votre équipe qui reçoit des e-mails. Mise en minuscules ; la partie avant `@` accepte jusqu'à 64 lettres, chiffres et `. _ % + -`. Elle ne peut plus changer ensuite. Omettez-la pour une adresse sur le domaine partagé. |
| `username` | Quand `email_address` est omis, la partie avant `@` sur le domaine partagé ; si `username` est omis aussi, l'adresse est aléatoire. Avec le `domain_id` d'un de vos propres domaines, c'est la partie avant `@` sur ce domaine. |
| `domain_id` | Une ligne de `GET /domains` : le sous-domaine partagé de votre équipe (`shared: true`), ou l'un de vos domaines vérifiés. |
| `name` | De 1 à 320 caractères ; l'adresse si omis. |
| `from_name` | Nom d'affichage des e-mails que la boîte envoie, 78 caractères au plus : un nom simple, sans `@`, `:`, `<`, `>`, saut de ligne, lien ni numéro de téléphone. |
| `kind` | `agent` (par défaut) ou `human`. |
| `expires_in` | Échéance de la boîte, par exemple `1h`, `24h` ou `7d` ; si omis, jamais. |
| `safety` | N'importe lequel des paramètres de sécurité. |
| `forwarding` | `true` ajoute un `receiving_address` sur le domaine partagé, pour transférer vers la boîte une messagerie que vous gardez ailleurs. |

| Réponse | Quand |
| --- | --- |
| `409 validation_error` | Une autre boîte utilise déjà cette adresse. Aucun autre nom n'est choisi à votre place. |
| `403 validation_error` | La limite de boîtes de votre forfait est atteinte. |
| `429 rate_limit_exceeded` | Trop de boîtes créées durant la dernière heure, ou l'examen des noms du domaine partagé a atteint la limite du jour. `retry-after` indique quand réessayer. |
| `422 validation_error` | Le domaine n'est pas vérifié ou ne reçoit pas d'e-mails, un `username` enfreint une règle ou est réservé, ou un paramètre enfreint une règle. |
| `503 name_review_unavailable` | Un nom du domaine partagé n'a pas pu être examiné pour le moment. Réessayez dans un instant. |

Les autres appels :

- `GET /inboxes` liste les boîtes, les plus récentes d'abord (`?kind=agent` ou `?kind=human` restreint la liste).
- `GET /inboxes/{id}` en lit une. Chaque `{id}` d'un chemin `/inboxes/{id}/…` accepte l'identifiant de la boîte ou son adresse e-mail.
- `PATCH /inboxes/{id}` modifie `name`, `from_name` ou `expires_in`.
- `DELETE /inboxes/{id}` supprime la boîte avec ses fils, ses brouillons et ses libellés, et révoque ses clés API. Un message qui est aussi arrivé dans une autre boîte ou à une adresse catch-all y reste.

## Adresses

### Votre propre domaine

Une boîte sur votre propre domaine exige que le domaine [reçoive des e-mails](/docs/fr/receiving) : vérifié, avec la réception activée et son enregistrement MX publié. Chaque message suit l'adresse à laquelle le serveur de l'expéditeur l'a remis :

1. à la boîte portant exactement cette adresse ;
2. sinon, pour `name+tag@`, à la boîte de `name@` ;
3. sinon, quand le catch-all du domaine est activé, à **Tous les e-mails reçus** sans boîte ; catch-all désactivé, l'adresse est refusée (`550 5.1.1`).

Un e-mail envoyé depuis l'adresse d'une boîte suit les règles de la boîte sur toutes les surfaces : `POST /emails`, l'endpoint de lot, le relais SMTP et MCP. Donnez à une boîte une adresse depuis laquelle votre application n'envoie pas déjà.

### Domaine partagé

Une boîte sur le domaine partagé n'a pas besoin de DNS. Chaque équipe reçoit son propre sous-domaine sur le domaine partagé de BillionSend, nommé d'après l'équipe. Omettez `email_address`, ou envoyez l'identifiant de la ligne partagée comme `domain_id`, et `username` nomme l'adresse :

```sh
curl -X POST "https://api.billionsend.com/inboxes" \
  -H "Authorization: Bearer bs_..." \
  -H "Content-Type: application/json" \
  -d '{ "username": "orders", "name": "Orders agent" }'
```

Sans `username`, l'adresse est aléatoire. Un nom d'utilisateur est refusé (`422`) quand il est réservé (postmaster, abuse, admin, security, support, noreply, no-reply, billing, hostmaster, webmaster, mailer-daemon, root), commence par `fwd-` ou ressemble à une marque connue. Un nom déjà pris répond `409`.

**Examen des noms.** Un nom d'utilisateur choisi, un `from_name` et le sous-domaine de l'équipe sont examinés avant d'être publiés, pour bloquer les noms qui se font passer pour une marque, une banque, une administration ou un rôle officiel. Un nom refusé répond `422`. Tant que l'examen ne peut pas répondre, vous obtenez `503 name_review_unavailable` ; le sous-domaine d'une nouvelle équipe est retenté jusqu'à ce qu'il passe, et après 24 heures l'équipe reçoit `team-` suivi de six caractères aléatoires. Au-delà de 20 noms refusés ou de 200 examens dans un jour UTC, la réponse est `429` jusqu'à minuit UTC.

Les adresses partagées suivent des règles propres, puisque le domaine appartient à toutes les équipes :

- Elles durent jusqu'à leur suppression, sauf si `expires_in` dit autre chose, et comptent dans la limite de boîtes de votre forfait. Une adresse que personne n'a utilisée pendant 90 jours est supprimée.
- Sur le forfait **Free**, et pour toute adresse dont le nom ressemble à une marque connue, elles ne répondent que dans leurs propres fils, aux expéditeurs dont le domaine s'est porté garant et aux adresses de connexion des membres de votre équipe. Sur un forfait payant, des personnes y démarrent des conversations, et un agent le fait quand son `send_policy` est `open` et que votre équipe a dépassé ses premiers envois ; sinon ses nouvelles conversations attendent une personne sous forme de brouillons. Chaque message à un inconnu est vérifié contre le phishing avant de partir. Un refus répond `403 inbox_send_policy`.
- Chaque e-mail va à 10 destinataires au plus. Une boîte envoie à 50 destinataires par jour au plus (`send_cap` de 1 à 50), et toutes les adresses partagées de votre équipe réunies atteignent 1 000 destinataires par jour UTC ; au-delà, `429 inbox_send_cap_reached`.
- `from` doit être exactement l'adresse de la boîte, et l'e-mail ne peut contenir ni `scheduled_at`, ni `reply_to`, ni pièces jointes, ni en-têtes personnalisés (`422`). `POST /emails/batch`, les campagnes et le relais SMTP refusent toujours une adresse partagée.
- `forward_to` n'accepte que des adresses de connexion de membres.

Les e-mails adressés à `postmaster@` et `abuse@` sur le domaine partagé vont à BillionSend, jamais à une boîte.

### Transférer une messagerie vers une boîte

`forwarding: true` sert pour une adresse dont les e-mails vivent ailleurs, comme une messagerie Google Workspace. La boîte reçoit un `receiving_address`, une adresse aléatoire sur le sous-domaine partagé de votre équipe : transférez la messagerie vers cette adresse, et la boîte reçoit les e-mails tout en répondant depuis sa propre adresse. Le domaine n'a alors besoin d'être vérifié que pour l'envoi.

## Expiration

`expires_in` est un nombre suivi de `h` ou `d`, de `1h` à `365d` ; si omis, la boîte n'expire jamais. Un `PATCH` avec un nouveau `expires_in` compte à partir de cet instant, et `null` supprime l'expiration. `expires_at` indique la date de fin.

À `expires_at`, la boîte s'arrête : les e-mails qui lui sont adressés sont refusés (`550 5.1.1`), les lectures répondent `404` et ses clés API cessent de fonctionner. Dans l'heure, elle est supprimée, avec un webhook `inbox.expired` suivi de `inbox.deleted`. Modifier l'expiration demande le rôle développeur, administrateur ou propriétaire.

## Fils

Chaque message d'une boîte appartient à un fil, et un fil contient les deux sens : ce que la boîte a reçu et ce qu'elle a envoyé.

- **Comment les réponses retrouvent leur fil.** Un e-mail envoyé par la boîte porte un jeton de fil dans son en-tête `References`. Une réponse atterrit dans le même fil quand elle porte ce jeton, quand son `In-Reply-To` désigne un message envoyé par la boîte, ou quand elle renvoie à un message antérieur du fil. Les objets ne regroupent jamais des fils.
- **Dossiers.** Un fil se trouve dans un seul dossier : `inbox`, `archive`, `spam`, `sent` ou `trash`. Un nouvel e-mail ramène un fil archivé ou envoyé dans `inbox`. `DELETE` déplace un fil dans `trash`, qui est vidé après 30 jours.
- **État de lecture.** Un `PATCH` avec `read` marque le fil entier. Un e-mail retenu ne rend jamais un fil non lu. Dans une boîte pour des personnes, ouvrir un fil le marque comme lu ; dans une boîte d'agent, l'état de lecture appartient à votre agent.
- **Libellés.** Jusqu'à 100 par boîte, noms de 1 à 64 caractères, couleurs au format `#RRGGBB`.

| Appel | Effet |
| --- | --- |
| `GET /inboxes/{id}/threads` | Les fils, dernière activité d'abord. Filtres : `folders`, `labels`, `read`, `include_quarantined`. |
| `GET /inboxes/{id}/threads/search` | Les mêmes filtres plus `query` (`"exact phrase"` et `-excluded` fonctionnent), `from`, `to`, `cc`, `bcc`, `has_attachment`, `start_date`, `end_date`. |
| `GET /inboxes/{id}/threads/{thread_id}` | Un fil. |
| `PATCH /inboxes/{id}/threads/{thread_id}` | Définit `read` ou `folder`. |
| `POST` / `PUT` / `DELETE …/threads/{thread_id}/labels` | Ajoute, remplace ou retire des libellés. |
| `DELETE /inboxes/{id}/threads/{thread_id}` | Déplace le fil dans la corbeille. |
| `GET /inboxes/{id}/threads/{thread_id}/emails` | Ses e-mails, les plus anciens d'abord. |

La recherche trouve des mots entiers, quelle que soit la casse, dans l'objet, l'expéditeur (adresse et nom d'affichage), les destinataires, le texte d'un e-mail reçu (messages antérieurs cités compris), les noms de ses pièces jointes et le texte de ses pièces jointes PDF, Word et Excel (une fois ce texte lu). Le texte chinois, japonais et coréen est découpé en mots. Chaque mot de `query` doit correspondre quelque part dans le même e-mail ; `from`, `to`, `cc` et `bcc` acceptent des mots d'une adresse ou d'un nom. Les e-mails envoyés sont recherchés par objet, expéditeur et destinataires.

`matched_email_id` est la meilleure correspondance du fil, et `highlights` marque les mots dans son objet, son expéditeur et ses destinataires (c'est `{}` quand seul le texte ou un nom de pièce jointe correspond). Un nouvel e-mail est cherchable une à deux secondes après son arrivée. Si la recherche est brièvement indisponible, l'appel répond `503` avec `search_unavailable` et un en-tête `Retry-After` ; tous les autres appels fonctionnent normalement.

Un e-mail d'un fil a `direction`, `from`, `to`, `cc`, `bcc`, `reply_to`, `subject`, `message_id`, `html`, `text`, `attachments`, `read` et `received_at`. Les e-mails reçus ajoutent `extracted_text` (la réponse, débarrassée du texte masqué), `screening`, `spam_verdict` et `virus_verdict`.

## Envoyer depuis une boîte

`POST /inboxes/{id}/emails` (`inboxes.send()` dans les SDK) démarre une nouvelle conversation depuis l'adresse de la boîte en un seul appel.

```sh
curl -X POST "https://api.billionsend.com/inboxes/{id}/emails" \
  -H "Authorization: Bearer bs_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1042-confirmation" \
  -d '{
    "to": "success@simulator.amazonses.com",
    "subject": "Your order 1042",
    "text": "It ships today. The invoice is attached.",
    "attachments": [{ "filename": "invoice.pdf", "content": "JVBERi0xLjQK..." }]
  }'
```

Il accepte `to`, `subject`, `html` et/ou `text`, et en option `cc`, `bcc`, `attachments` et `requires_approval`. Les règles de la boîte décident comme pour une réponse, et les réponses sont celles d'une réponse : `200` avec `{ "id", "thread_id" }`, ou `202` avec le brouillon quand les règles retiennent l'envoi (une boîte qui n'a pas le droit de démarrer des conversations, un premier destinataire au-delà de la montée en charge, `requires_approval: true`). Une clé limitée à une boîte peut l'appeler pour sa propre boîte.

Les **pièces jointes** sont celles que prend `POST /emails` : `filename` et `content` en base64, avec en option `content_type` et `content_id` pour une image intégrée. Un `path` distant répond `422`. Les réponses, transferts, nouveaux envois et brouillons les acceptent tous, jusqu'à 10 MiB décodés au total (un transfert compte aussi les fichiers de l'original) ; les programmes et les types de fichiers déguisés répondent `422`, et une boîte du domaine partagé n'en accepte aucune.

## Répondre et transférer

```sh
curl -X POST "https://api.billionsend.com/inboxes/{id}/threads/{thread_id}/emails/{email_id}/reply" \
  -H "Authorization: Bearer bs_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1042-reply" \
  -d '{ "text": "Thanks, your order ships today." }'
```

Une réponse part vers le `Reply-To` du message, sinon vers son expéditeur. `reply_all` ajoute les autres adresses `to` et `cc` en `cc` ; `bcc` n'est jamais copié. Un envoi accepte 50 destinataires au plus. `…/forward` exige `to`, accepte une note, et cite l'original avec ses pièces jointes, plus les `attachments` que vous ajoutez (jusqu'à 10 MiB au total). Les deux acceptent `attachments` et `requires_approval: true` pour qu'une personne approuve l'envoi. Une réponse d'une boîte d'agent porte `Auto-Submitted: auto-replied`.

| Réponse | Signification |
| --- | --- |
| `200` | Envoyé : `{ "id", "thread_id" }`. |
| `202` | Retenu pour une personne : le brouillon, avec `status: "pending_approval"` et ses `approval_reasons`. |
| `403 inbox_send_policy` | Les règles de la boîte refusent l'envoi purement et simplement. |
| `403 email_quarantined` | L'e-mail est retenu en quarantaine, ou contient un virus. |
| `403 restricted_api_key` | Une clé limitée à une boîte qui tente d'atteindre une autre boîte. |
| `429 inbox_send_cap_reached` | Le plafond quotidien de la boîte est atteint ; `retry-after` compte jusqu'à minuit UTC. |

Pour répondre à n'importe quel e-mail reçu, dans une boîte ou non, utilisez [`POST /emails/receiving/{id}/reply`](/docs/fr/receiving).

## Brouillons et approbation

Un brouillon est autonome pour une nouvelle conversation, ou une réponse avec `thread_id` et `reply_to_email_id`. Son `status` :

| `status` | Signification |
| --- | --- |
| `draft` | En cours de rédaction ; rien ne l'envoie avant `…/send`, ou avant son `send_at`. |
| `pending_approval` | Un envoi a été retenu et attend une personne. `approval_reasons` dit pourquoi. Il expire après 7 jours. |
| `sent` | Envoyé ; `email_id` désigne l'e-mail. |
| `rejected` | Une personne l'a refusé. |
| `expired` | Personne ne l'a approuvé en 7 jours. |

| Appel | Effet |
| --- | --- |
| `POST /inboxes/{id}/drafts` | Crée un brouillon : `to`, `cc`, `bcc`, `subject`, `text`, `html`, `attachments`, plus `thread_id` et `reply_to_email_id` pour une réponse. Un brouillon de réponse ne copie pas les destinataires : définissez `to` avant l'envoi. |
| `GET /inboxes/{id}/drafts` | Les brouillons non envoyés, mis à jour le plus récemment d'abord. |
| `GET` / `PATCH` / `DELETE /inboxes/{id}/drafts/{draft_id}` | Lit, modifie (définir `text` ou `html` remplace tout le corps, et `attachments` remplace toute la liste) ou supprime un brouillon ; `409` une fois envoyé. |
| `POST /inboxes/{id}/drafts/{draft_id}/send` | L'envoie. `200` avec l'`id` et le `thread_id` de l'e-mail envoyé, `202` quand il est retenu, `422` sans destinataire. |
| `POST /inboxes/{id}/drafts/{draft_id}/reject` | Refuse un brouillon (approbateurs uniquement). |

Un brouillon garde ses `attachments` chiffrés, à part de son corps, et les relit par position sous la forme `id`, `filename`, `content_type` et `size`, jamais le contenu. Ils partent avec l'e-mail quand le brouillon est envoyé, et un envoi retenu garde avec son brouillon les fichiers qu'il portait. Une fois un brouillon envoyé, refusé, expiré ou supprimé, ses fichiers disparaissent, et la purge de contenu à 30 jours supprime ceux qui restent.

**Envois programmés.** `send_at` sur `POST` ou `PATCH` (une extension BillionSend) envoie le brouillon plus tard, au nom de la personne qui l'a défini (modifier le contenu d'un brouillon programmé fait de l'éditeur celui au nom de qui il part) : une heure ISO 8601 avec décalage, ou une heure relative comme `"in 2 hours"`, au plus 30 jours à l'avance ; une heure déjà passée l'envoie dans la minute, et `null` annule. Le brouillon doit avoir un destinataire à ce moment, et seul un `draft` peut être programmé : un brouillon en attente d'approbation répond `409`. Quand `send_at` arrive, l'envoi applique toutes les règles et limites comme un envoi fait à cet instant. Envoyé, le brouillon passe à `sent` ; retenu par les règles de la boîte, à `pending_approval` ; refusé (la clé qui l'a programmé a été révoquée, la boîte n'existe plus, une limite a été atteinte), il reste un `draft` avec `send_at` revenu à `null`, le nom du refus dans `send_error` et un webhook `inbox.draft.send_failed` qui porte `error: { name, message }`. Le reprogrammer efface `send_error`. Avec `send_at`, créer un second brouillon de réponse pour le même e-mail répond `409` au lieu de renvoyer le brouillon existant.

**Qui approuve.** Une personne dans le tableau de bord, ou une clé API à accès complet de l'équipe qui n'est pas limitée à une boîte, approuve en envoyant : l'envoi contourne les règles qui retiennent les e-mails d'agent. Un agent ne peut pas approuver : une clé limitée à une boîte ou un client MCP qui envoie un brouillon en attente reçoit `403 approval_required`. Dans le tableau de bord, tout membre approuve, modifie ou abandonne les brouillons sous l'onglet **À examiner** de la boîte, et les propriétaires reçoivent un e-mail par jour tant que quelque chose attend.

Raisons pour lesquelles un envoi est retenu :

| Raison | Retenu parce que |
| --- | --- |
| `approval_required` | La requête a demandé une personne (`requires_approval: true`). |
| `require_approval` | La boîte fait approuver chaque envoi. |
| `send_policy` | Un destinataire n'est pas autorisé par la politique d'envoi de la boîte. |
| `ramp` | Trop de nouveaux destinataires aujourd'hui pour une boîte récente. |
| `private_code` | Il contient un code ou un lien de connexion que la boîte a reçu. |
| `loop_guard:<reason>` | Il répond à un message automatique (absence du bureau, liste de diffusion, rebond). |
| `loop_burst` | Trop de réponses automatiques à une même adresse en une heure. |
| `reply_to_redirect` | Le Reply-To du message pointe vers une autre organisation. |

## Paramètres de sécurité

`GET /inboxes/{id}/safety` lit les règles d'une boîte, et `PATCH` modifie n'importe laquelle :

```sh
curl -X PATCH "https://api.billionsend.com/inboxes/{id}/safety" \
  -H "Authorization: Bearer bs_..." \
  -H "Content-Type: application/json" \
  -d '{
    "accept_from": "allowlist",
    "allowlist": ["*@billing.example.net", "maria@example.org"]
  }'
```

| Paramètre | Effet |
| --- | --- |
| `accept_from` | Les e-mails de qui parviennent à la boîte : `anyone` ; `verified`, les expéditeurs dont le domaine se porte garant de l'adresse From (plus les propriétaires, la liste d'autorisation et les fils connus) ; ou `allowlist`, uniquement les propriétaires, la liste d'autorisation et les fils connus. Le reste est mis en quarantaine. |
| `allowlist` | Jusqu'à 500 entrées : `name@domain`, ou `*@domain` pour un domaine et ses sous-domaines. |
| `owner_addresses` | Jusqu'à 50 autres adresses traitées comme propriétaires de la boîte, en plus des adresses de connexion des membres de votre équipe. Ignoré sur le domaine partagé. |
| `screening` | Note les e-mails d'expéditeurs externes pour l'injection de prompt et le phishing (boîtes d'agent). |
| `extract_codes` | Extrait les codes de vérification et les liens de connexion des e-mails. |
| `send_policy` | `reply_only` ; `allowlist`, qui ajoute de nouvelles conversations avec les propriétaires et la liste d'autorisation (pas sur le domaine partagé) ; ou `open`, n'importe qui, une fois que l'équipe a dépassé ses premiers envois. |
| `require_approval` | Chaque envoi depuis la boîte attend une personne. |
| `private_codes` | Un code ou un lien de connexion que la boîte a reçu ne peut être envoyé qu'aux propriétaires et à la liste d'autorisation. |
| `send_cap` | Destinataires auxquels la boîte peut envoyer par jour UTC sans personne : de 1 à 100 000, ou `null` pour aucun plafond (de 1 à 50 sur le domaine partagé). |
| `forward_to` | Jusqu'à 5 adresses qui reçoivent une copie de chaque message distribué sauf le spam : adresses de connexion de membres de l'équipe ou adresses de propriétaires. Une copie qui ne peut pas partir tout de suite est retentée jusqu'à ce qu'elle soit envoyée, refusée définitivement, ou que deux jours se soient écoulés ; elle n'est jamais envoyée deux fois. |

Un paramètre qui enfreint une règle répond `422` avec la raison. Une clé limitée à une boîte ne peut pas modifier ces paramètres (`403 restricted_api_key`), pas plus qu'une clé d'agent. Un client MCP peut les lire mais pas les modifier. Seul un propriétaire, un administrateur ou un développeur les modifie, dans le tableau de bord ou avec une clé API à accès complet. [Sécurité des agents](/docs/fr/agent-safety) explique ce que fait chacun.

## Quarantaine

Un e-mail que les règles d'une boîte ne laissent pas entrer est mis en quarantaine : conservé, listé et libérable, jamais supprimé ni renvoyé à son expéditeur. Il ne déclenche ni `email.received` ni `inbox.email.received` avant d'être libéré, et les agents ne le voient jamais.

`GET /inboxes/{id}/quarantine` liste les messages retenus avec `id`, `from`, `subject`, `quarantine_reason`, `sender_trust`, `injection_score`, `phishing_score` et `virus_signature`, sans contenu. `POST /inboxes/{id}/quarantine/{email_id}/release` en distribue un, et `{ "trust_sender": true }` ajoute aussi son expéditeur à la liste d'autorisation. Les deux exigent une clé à accès complet qui n'est pas limitée à une boîte. Les personnes libèrent depuis l'onglet **À examiner** de la boîte, et les clients MCP avec `receiving:manage` utilisent `release_email`. Qui peut libérer quelle retenue est expliqué dans [Sécurité des agents](/docs/fr/agent-safety).

## Codes de vérification

`GET /inboxes/{id}/codes/latest` renvoie le code de vérification ou le lien de connexion le plus récent que la boîte a reçu, pour qu'un agent ne lise jamais de HTML :

```sh
curl "https://api.billionsend.com/inboxes/{id}/codes/latest?from=example.org&wait=30" \
  -H "Authorization: Bearer bs_..."
```

```json
{
  "object": "verification_code",
  "status": "found",
  "kind": "link",
  "code": null,
  "url": "https://app.example.org/verify?token=Qm9vdHN0cmFwLTQ4MjkxMw",
  "link_domain_matches_sender": true,
  "email_id": "155252fb-e93e-45ee-8c19-5080a929c28b",
  "from": "no-reply@example.org",
  "received_at": "2026-10-12T14:03:11.229Z",
  "sender_trust": "external"
}
```

- `kind` vaut `otp` (code dans `code`) ou `link` (adresse dans `url`, avec `link_domain_matches_sender`).
- `from` restreint à un expéditeur ; `wait` (de 0 à 50 secondes) attend qu'un code arrive ; `max_age` (de 60 à 86 400 secondes, 600 par défaut) ignore les codes plus anciens ; `since` ignore les e-mails reçus à cet instant ou avant, donc passez le `received_at` d'un code déjà utilisé pour attendre le suivant.
- `status` vaut `found`, `none`, `ambiguous` (deux codes également probables, donc aucun n'est renvoyé) ou `timeout`. La réponse est toujours `200`.
- Les codes ne viennent jamais d'un e-mail en quarantaine, d'expéditeurs qui ont échoué à l'authentification, ni d'une boîte où `extract_codes` est désactivé. Chaque lecture est consignée dans l'activité de la boîte.

## Flux d'événements

`GET /inboxes/events` est un flux d'événements envoyés par le serveur (SSE) de tout ce qui se passe dans vos boîtes, à l'instant où c'est validé. Les événements portent les noms des événements de webhook (`inbox.email.received`, `inbox.thread.created`, `inbox.draft.created`, `email.received` et les autres événements `inbox.*`) et le `data` de la charge utile du webhook. `GET /inboxes/{id}/events` diffuse une seule boîte et se termine quand cette boîte est supprimée ou expire.

```sh
curl -N "https://api.billionsend.com/inboxes/events?types=inbox.email.received" \
  -H "Authorization: Bearer bs_..." \
  -H "Accept: text/event-stream"
```

```text
retry: 1000

id: 812.40.1790000000
event: inbox.email.received
data: {"type":"inbox.email.received","created_at":"2026-11-15T09:20:30.131Z","inbox_id":"7eeb9517-aed7-40d7-ad65-500be42ed147","data":{"source":"system","inbox_id":"7eeb9517-aed7-40d7-ad65-500be42ed147","thread_id":"...","email_id":"...","email":{}}}

: keepalive
```

- Envoyez la clé dans un en-tête `Bearer`, comme pour toute requête. L'`EventSource` des navigateurs ne peut pas le définir : utilisez `fetch` et lisez le corps, ou tout client SSE qui accepte des en-têtes.
- `types` restreint le flux à certains événements, séparés par des virgules ; `/inboxes/{id}/events` envoie toujours `inbox.deleted` et `inbox.expired`, les événements qui y mettent fin. Chaque événement ne contient que des métadonnées, comme un webhook : ni corps, ni code, ni lien. Lisez le message avec les endpoints de [réception](/docs/fr/receiving).
- **Reprise.** Chaque événement a un `id`. Un client qui se reconnecte avec `Last-Event-ID` (ou `?last_event_id=`) reçoit ce qu'il a manqué, dans l'ordre, avant les événements en direct. Les événements sont conservés 24 heures ; une reconnexion depuis un `id` plus ancien reçoit d'abord un événement `stream.gap`, ce qui signifie que des événements peuvent manquer et qu'il faut relire les listes.
- Un flux démarre sans rejeu quand il n'a pas de `Last-Event-ID`. Le serveur le ferme toutes les 10 minutes environ, et quand l'API redémarre : reconnectez-vous avec le dernier `id` vu. `retry: 1000` demande à un client d'attendre une seconde. Une ligne de commentaire toutes les 15 secondes empêche les proxys de fermer un flux inactif.
- Une clé de portée équipe ouvre `/inboxes/events`. Une clé restreinte à un domaine, ou à une boîte, ouvre `/inboxes/{id}/events` pour une boîte qu'elle peut atteindre. Une clé d'envoi uniquement ne peut pas ouvrir de flux.
- Un agent (une clé limitée à une boîte, ou une connexion MCP) ne reçoit jamais `inbox.email.quarantined`, ni en direct ni en rejeu, car il ne lit jamais les e-mails retenus ; le nommer dans `types` donne `403 restricted_api_key`.
- Un flux se ferme en quelques secondes dès que sa clé est révoquée, que la personne qui a créé la clé quitte l'équipe, ou que sa boîte est supprimée ou expire.
- Chaque clé peut tenir 5 flux à la fois sur chaque processus API et chaque équipe 25 ; un de plus répond `429 too_many_streams` avec `retry-after`. Un seul flux pour toute l'équipe suffit à la plupart des agents.

`wait` sur `/emails/receiving` et `codes/latest` est réveillé par les mêmes événements, donc attendre ne coûte rien tant qu'aucun e-mail n'arrive.

## Clés API limitées à une boîte

Donnez à chaque agent une clé qui n'atteint que sa propre boîte. Voir [Clés API](/docs/fr/api-keys).

```sh
curl -X POST "https://api.billionsend.com/api-keys" \
  -H "Authorization: Bearer bs_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "orders agent",
    "permission": "full_access",
    "inbox_id": "7eeb9517-aed7-40d7-ad65-500be42ed147"
  }'
```

- Elle exige `permission: "full_access"` et ne peut pas prendre aussi un `domain_id`. Une boîte porte 5 clés actives au plus, en dehors de la limite de 25 de l'équipe.
- La clé lit sa boîte (fils, e-mails, brouillons, libellés, codes, flux d'événements, et `/emails/receiving` limité à cette boîte), répond, transfère, écrit des brouillons et les envoie, envoie de nouveaux e-mails depuis sa boîte, et n'envoie que depuis l'adresse de la boîte (`403 restricted_api_key` pour un autre `from` ; `550 5.7.1` via SMTP).
- Tout le reste répond `403 restricted_api_key` : elle ne peut pas modifier les paramètres de sécurité, lister ou libérer la quarantaine, approuver des brouillons, créer des clés ni atteindre une autre boîte.
- Elle cesse de fonctionner quand sa boîte expire, et supprimer la boîte la révoque.

Dans le tableau de bord, les propriétaires, administrateurs et développeurs choisissent la boîte sous **Limiter à une boîte de réception** à la création d'une clé.

## Webhooks

Les événements de boîte (`inbox.created`, `inbox.thread.created`, `inbox.email.received`, `inbox.email.sent`, `inbox.email.quarantined`, `inbox.expired`, les événements `inbox.draft.*` et d'autres) ne vont qu'aux endpoints qui les nomment, jamais à un endpoint abonné à tous les événements. Un endpoint peut être limité à certaines boîtes avec `inbox_ids`. `email.received` se déclenche toujours pour les e-mails de boîte une fois distribués. Charges utiles : [Webhooks](/docs/fr/concepts/webhooks).

## Activité

Tout ce qui se fait dans une boîte est consigné : envois et décisions des règles, refus, brouillons, approbations, libérations, lectures de code, changements de sécurité, suppressions et clés. L'onglet **Activité** de la boîte le liste avec l'auteur : une personne, une clé API ou une application connectée. Les décisions ne gardent que des codes de motif, jamais de contenu, de codes ni d'adresses.

## Limites

| Limite | Valeur |
| --- | --- |
| Boîtes de réception | 3 sur Free, 25 sur Starter, illimitées sur Pro et Scale. |
| Boîtes créées par heure | 10 sur Free, 60 sur Starter, 600 sur Pro et Scale. |
| E-mails par boîte | 200 messages acceptés par heure glissante pour une boîte d'agent, 2 000 pour une boîte pour des personnes. Au-delà, les expéditeurs reçoivent `452 4.2.2` et réessaient plus tard. |
| Envois | `send_cap` destinataires par jour UTC. Une nouvelle boîte atteint de nouveaux destinataires progressivement : 10 le premier jour d'envoi, puis 20, 40, 80, 160 et ainsi de suite, jusqu'au plafond. |
| Destinataires par envoi | 50 (`to`, `cc` et `bcc` ensemble) ; 10 depuis une adresse partagée. |
| Pièces jointes par envoi | 10 MiB décodés au total ; aucune depuis une adresse partagée. |
| Domaine partagé | 1 000 destinataires par jour UTC pour toutes les adresses partagées de votre équipe ; une boîte partagée inutilisée pendant 90 jours est supprimée. |
| Libellés | 100 par boîte. |
| Listes de sécurité | 500 entrées de liste d'autorisation, 50 adresses de propriétaire, 5 adresses `forward_to`. |
| Clés limitées à une boîte | 5 actives par boîte. |
| Analyse | 200 messages par boîte et par jour ; au-delà, les e-mails qui doivent être analysés sont mis en quarantaine. |
| Attente | 50 secondes par requête ; 20 attentes simultanées par équipe sur chaque processus API. |
| Flux d'événements | 5 par clé API et 25 par équipe en même temps sur chaque processus API ; les événements sont rejoués pendant 24 heures. |
| Brouillons et corbeille | Un brouillon en attente expire après 7 jours ; un fil mis à la corbeille est supprimé après 30. |
| Rétention | Les e-mails de boîte suivent la rétention des e-mails reçus : 30 jours. |

Les boîtes elles-mêmes ne coûtent rien : un e-mail reçu compte une fois par message dans votre limite de réception, jamais dans votre volume d'envoi, comme dans [Réception](/docs/fr/receiving).

## Tableau de bord

**Boîtes de réception** dans la barre latérale liste vos boîtes sous les onglets **Toutes**, **Agent** et **Personnes**, avec ce qui demande de l'attention : brouillons à approuver, fils non lus et messages en quarantaine. Une ligne épinglée **Tous les e-mails reçus** ouvre tous les e-mails que vos domaines ont reçus. La page d'une boîte a quatre onglets : **Conversations** (lire, répondre et approuver des brouillons sur place), **À examiner** (brouillons et quarantaine), **Sécurité et règles** et **Activité**.

Tout membre peut traiter les fils d'une boîte, approuver des brouillons et libérer la quarantaine. Les propriétaires, administrateurs et développeurs peuvent aussi créer, modifier et supprimer des boîtes, changer les règles de sécurité, créer des clés limitées à une boîte, supprimer des e-mails reçus et activer le catch-all. Voir [rôles d'équipe](/docs/fr/team-roles).

## MCP

Les [clients MCP](/docs/fr/mcp) travaillent avec les boîtes sous trois permissions : `receiving:read` (lire les e-mails, les attendre, lire les codes, lister les boîtes, fils, libellés et brouillons, rechercher dans les fils, lire les règles de sécurité), `receiving:reply` (répondre, transférer, envoyer depuis une boîte, écrire, envoyer et supprimer des brouillons, organiser les fils et les libellés) et `receiving:manage` (créer, modifier et supprimer des boîtes, lister et libérer la quarantaine). Un client MCP voit toujours les e-mails comme un agent : sans les e-mails retenus et avec le texte des messages encadré comme non fiable. Il n'approuve jamais de brouillons, et `create_inbox` accepte `accept_from` et aucun autre paramètre de sécurité ; il ne modifie jamais les règles de sécurité d'une boîte.

## Notes sur l'API

- Créer une boîte ou un brouillon renvoie l'objet complet.
- `email_address` est facultatif : s'il est omis, la boîte reçoit une adresse permanente aléatoire sur le domaine partagé.
- `kind` vaut `agent` par défaut, donc une boîte créée sans lui reçoit les protections d'un agent.
- Il n'y a pas d'agent hébergé : `GET /inboxes/{id}/agent` renvoie des `instructions`, `tone` et `actions` vides, et `PATCH /inboxes/{id}/agent` répond `422`.
- Non pris en charge : les `headers` personnalisés sur les réponses, transferts et envois de brouillon, et les pièces jointes `path` (URL distante). Chacun répond `422` sauf si sa valeur est vide.
- Une réponse, un transfert ou un envoi de brouillon retenu par les règles de la boîte répond `202` avec le brouillon au lieu de `200` avec l'e-mail : vérifiez que `object` vaut `inbox_draft` avant de considérer le résultat comme envoyé.
- Erreurs de boîte : `403 inbox_send_policy`, `429 inbox_send_cap_reached`, `403 approval_required`, `403 email_quarantined` et `503 name_review_unavailable` (voir [Erreurs](/docs/fr/api-reference/basics)).
- Les événements de webhook `inbox.*` sont sur abonnement ; `inbox.thread.assigned` et `inbox.thread.unassigned` ne sont pas envoyés.
