Boîtes aux lettres d'agent

Une boîte aux lettres d'agent est une boîte de réception adressable que votre code gère via le API. Lisez et filtrez ses fils de discussion, répondez aux messages ou composez un nouveau courrier sans faire tourner un serveur IMAP ni analyser du MIME brut.

Une boîte aux lettres réside sur le domaine partagé inbox.ai, ou sur votre propre domaine d'envoi activé pour la réception. Son adresse est réservée dès sa création et reste la vôtre : la partie locale est attribuée à votre espace de travail et n'est jamais cédée à quiconque, même après la suppression de la boîte aux lettres.

Adresses

Chaque boîte aux lettres possède une adresse, {local_part}@inbox.ai. Vous obtenez une adresse de deux façons :

Générée : omettez la partie locale et nous en générons une sans collision pour vous (a7f3k2@inbox.ai). Toujours disponible.
Personnalisée : demandez une partie locale spécifique (support@inbox.ai). Les identifiants personnalisés sont uniques à l'échelle mondiale, attribués selon l'ordre d'arrivée, et compris dans les forfaits payants ; un espace de travail gratuit utilise des adresses générées.

Une adresse est immuable une fois créée. Pour la changer, créez une nouvelle boîte aux lettres et supprimez l'ancienne. L'ancienne partie locale est conservée pendant 30 jours (sa fenêtre de restauration) avant de pouvoir être réclamée à nouveau, et reste réservée à votre espace de travail.

Fils de discussion et messages

Le courrier reçu et envoyé est regroupé en fils de discussion, un par conversation. Un fil contient les adresses participantes, un compteur de non-lus, la direction du dernier message (inbound ou outbound) et l'horodatage de l'activité la plus récente. Les réponses se rattachent au fil auquel elles répondent ; une nouvelle composition ouvre un nouveau fil.

Chaque message expose les en-têtes, le texte brut extrait sans l'historique des citations, et les pièces jointes. Les corps originaux sont disponibles pendant 30 jours ; le MIME brut n'est disponible que pour les messages reçus. Les identifiants de message sont préfixés par la direction : rem_ pour un message reçu, em_ pour un message envoyé.

Décider ce qui entre

Deux contrôles se placent devant la boîte de réception, tous deux vérifiés par rapport à l'expéditeur de l'enveloppe plutôt qu'à l'en-tête From: falsifiable :

Politique de réception : le comportement par défaut de la boîte aux lettres.
- open accepte tout ce qui passe l'authentification.
- replies_only n'accepte que le courrier qui prolonge un fil déjà présent dans la boîte aux lettres.
- allowlist n'accepte que les expéditeurs autorisés par vos règles, plus les réponses à un fil existant.
- drop rejette tout, sans exception.
Règles de réception : entrées d'autorisation ou de blocage par expéditeur, appliquées sur une adresse complète ou un domaine (une règle de domaine couvre aussi ses sous-domaines). Un blocage l'emporte toujours sur une autorisation.

Le courrier bloqué par une règle, ou échouant à DMARC, est tout de même stocké dans la boîte aux lettres et reste lisible : il est classé hors de la boîte de réception plutôt que supprimé, et ne déclenche aucun webhook. La seule exception est une boîte aux lettres configurée sur drop, qui rejette tout à l'entrée au lieu de le classer.

Envoi

Une boîte aux lettres envoie de deux façons via le API : répondre à un message (le message sortant se rattache à ce fil) ou composer un nouveau message (ce qui ouvre un nouveau fil). Dans le tableau de bord, ouvrez un message et choisissez Transférer pour envoyer son corps original et ses pièces jointes à de nouveaux destinataires, dans la fenêtre de 30 jours du contenu original. Le courrier part depuis l'adresse de la boîte aux lettres, avec le nom d'affichage et le Reply-To par défaut que vous avez configurés. Le statut de livraison se rattache au message envoyé, ce qui vous permet de voir si une réponse a été livrée ou rejetée.

Événements

Abonnez-vous à la famille de webhooks email_mailbox.* pour piloter un agent sans interrogation périodique : email_mailbox.message_received (le courrier entrant a atteint la boîte de réception), email_mailbox.thread_created, et les événements de statut de livraison pour les messages que vous envoyez. Seul le courrier de la boîte de réception est distribué ; le spam et le courrier bloqué par les règles sont stockés silencieusement, de sorte qu'une boîte aux lettres inondée ne peut pas se transformer en avalanche de webhooks. Le courrier de la boîte de réception déclenche aussi l'événement standard email.received, pour que vos intégrations entrantes existantes continuent de fonctionner.

Pour une vue en temps réel sans infrastructure webhook, connectez-vous à GET /v1/email/mailboxes/{mailbox_id}/events. Le flux SSE envoie le type d'événement, l'identifiant du fil et l'identifiant du message pour l'activité de la boîte aux lettres, y compris le spam et les arrivées bloquées. Récupérez les messages complets avec ces identifiants. Le flux ne rejoue pas les événements après une déconnexion. Utilisez les webhooks pour une livraison durable, et les endpoints de liste pour rattraper les lacunes.

Rétention et suppression

Le niveau de rétention d'une boîte aux lettres détermine la durée pendant laquelle vous pouvez lire les en-têtes de message, le texte extrait et les pièces jointes, à compter de l'envoi ou de la réception. La valeur par défaut est 30 jours. Si votre forfait inclut une rétention de 90 ou 365 jours, définissez retention_tier à la création ou à la mise à jour. Un niveau non inclus dans votre forfait est refusé avec E17048.

Contenu ou action	Fenêtre de rétention
En-têtes de message, texte extrait et pièces jointes	Niveau sélectionné : 30, 90 ou 365 jours
Corps HTML et texte brut originaux	30 jours quel que soit le niveau
MIME brut pour les messages reçus	30 jours quel que soit le niveau ; les messages envoyés n'ont pas de MIME brut stocké
Transfert d'un message dans le tableau de bord	Le contenu original doit être dans sa fenêtre de 30 jours
Lecture du texte extrait ou réponse avec un nouveau contenu	Disponible tant que le message est conservé

Par exemple, au jour 40, un message dans une boîte aux lettres à 90 jours dispose encore d'un texte extrait lisible et interrogeable ainsi que de pièces jointes conservées. Vous pouvez répondre avec un nouveau contenu, mais vous ne pouvez pas ouvrir le corps original, télécharger son MIME brut ni le transférer. Le texte extrait est limité à 64 Kio par message et peut omettre des parties de l'original. Les pièces jointes stockées avant l'activation de la rétention étendue conservent leur expiration initiale d'environ 31 jours ; changer de niveau ne les migre pas. Augmenter le niveau ne permet pas de récupérer un contenu déjà supprimé.

Les messages cessent d'être renvoyés par le API lorsque leur rétention expire. Un balayage horaire traite la suppression en arrière-plan ; le nettoyage physique peut être en retard par rapport à l'expiration API.

Abaisser le niveau prend effet immédiatement en lecture : tout ce qui est plus ancien que le nouveau seuil cesse d'être renvoyé aussitôt. Vous disposez de dix minutes pour annuler, et dix minutes est la seule garantie : remontez le niveau dans cette fenêtre et rien n'est perdu. Au-delà, les messages isolés deviennent éligibles à la suppression et le prochain balayage horaire les emporte, de sorte qu'une remontée ultérieure ne récupère que ce que le balayage n'a pas encore atteint.

Remonter vers un niveau inclus dans votre forfait est accepté à tout moment, y compris pendant l'application d'un changement précédent. La mise à jour en arrière-plan est indépendante de la fenêtre d'annulation de dix minutes. Abaisser une seconde fois est accepté une fois que le premier changement a mis à jour chaque message stocké. La mise à jour démarre toutes les dix minutes et peut prendre des heures pour les grandes boîtes aux lettres. Tant qu'elle n'est pas terminée, le API renvoie E17050 ; réessayez plus tard.

Si votre forfait fixe un quota de stockage fini pour les boîtes aux lettres, un seul quota est partagé entre toutes les boîtes aux lettres actives ou restaurables. Chaque boîte aux lettres indique sa part sous size_bytes. Un forfait sans quota fini offre un stockage illimité. Lorsque l'ensemble des boîtes aux lettres atteint le quota, l'envoi est refusé avec E17049 jusqu'à ce que vous libériez de l'espace dans l'une d'entre elles.

Supprimer une boîte aux lettres arrête immédiatement la réception de courrier. La boîte aux lettres peut être restaurée pendant 30 jours, tandis que l'expiration normale de la rétention des messages se poursuit. Après 30 jours, la suppression définitive efface la boîte aux lettres et ses messages restants. Une fois la suppression définitive lancée, la restauration est refusée même si le nettoyage est encore en cours. L'adresse reste réservée à votre espace de travail.

Étapes suivantes

Réclamez votre première boîte aux lettres : le parcours type API, de la création à la réponse.
Construire avec l'IA : pilotez des boîtes aux lettres depuis un agent via le serveur MCP.

Ressources associées

Poursuivez avec la documentation, les guides et les exemples sur ce sujet. Les ressources sont en anglais.

Regarder le guideGetting started with email Explorer la fonctionnalitéEmail Suivre le parcours d'apprentissageBuild your first integration Guide d'implémentationSend your first email

Essayez la pratique et obtenez un guide d'implémentation