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 l'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 l'un de vos propres domaines d'envoi. 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.

Sur votre propre domaine, transmettez domain à la création et choisissez n'importe quelle partie locale, par exemple support@acme.com. La façon dont le courrier atteint la boîte aux lettres dépend de la configuration du domaine :

• Réception activée : le courrier arrive directement dès que les enregistrements MX du domaine pointent vers nous. Consultez Recevoir des e-mails.
• Réception non activée : la propriété du domaine doit être vérifiée, et vos enregistrements MX restent inchangés. La boîte aux lettres reçoit une forwarding_address, par exemple k7q2mzxw4h6p5ra3@eu1.inbound.bird.com. Chez votre fournisseur de messagerie actuel, ajoutez pour support@acme.com une règle de transfert qui pointe vers cette adresse. Le courrier transféré arrive dans la boîte aux lettres, et les réponses comme les nouveaux messages partent toujours depuis support@acme.com.

Pour une boîte aux lettres existante sur votre propre domaine sans adresse de transfert, ouvrez Mailbox settings et choisissez Set up forwarding. L'adresse, les messages, la politique de réception et la conservation de la boîte aux lettres restent inchangés. Cette opération nécessite l'autorisation d'écriture sur la gestion des boîtes aux lettres et une propriété de domaine vérifiée dans l'espace de travail. Un domaine réservé pour la réception par un autre espace de travail ne peut pas obtenir ici de nouvelle adresse de transfert.

L'équivalent API est POST /v1/email/mailboxes/{mailbox_id}/forwarding-address, sans corps de requête. Il renvoie la boîte aux lettres complète avec son forwarding_address. Répéter la requête renvoie la même adresse, y compris après une suppression et une restauration ; elle ne renouvelle pas l'adresse et ne réactive pas une boîte aux lettres suspendue. La commande CLI est bird email mailboxes forwarding-address create <mailbox-id>.

Créer une adresse ne configure pas le transfert chez votre fournisseur, ne modifie pas le DNS et ne vérifie pas la livraison. Si votre fournisseur reçoit déjà le courrier, conservez ses enregistrements MX et ajoutez-y la règle de transfert. Si les enregistrements MX pointent vers nous, préparez d'abord la boîte aux lettres et la règle de transfert chez votre fournisseur, puis faites pointer les enregistrements MX vers ce fournisseur. Laissez la réception activée pendant la propagation du changement DNS. Testez le transfert avant de désactiver la réception directe.

Gmail et Google Workspace envoient un message de confirmation à toute nouvelle adresse de transfert. Ouvrez-le dans cette boîte aux lettres et suivez ses instructions pour terminer la configuration. Microsoft 365 peut exiger qu'un administrateur autorise le transfert externe. Avec la politique replies_only ou allowlist, vérifiez le courrier bloqué ; vérifiez aussi le spam et les règles de réception. Une politique drop ne conserve pas la confirmation : modifiez explicitement la politique avant de demander une nouvelle confirmation. Une boîte aux lettres suspendue doit être réactivée pour accepter normalement les messages.

Conservez une copie chez votre fournisseur pendant les tests. Envoyez un nouveau message depuis un autre compte vers l'adresse d'origine de la boîte aux lettres, puis ouvrez le message reçu dans cette boîte aux lettres. Son adresse Delivered to doit correspondre à la forwarding_address pour prouver la livraison par cette voie. L'API l'expose sous la forme delivered_to. Les compteurs de messages de la boîte aux lettres incluent l'activité sortante et ne vérifient pas le transfert.

Pour revenir à la livraison directe, activez la réception, rétablissez nos enregistrements MX et testez la livraison directe avant de supprimer la règle de transfert de votre fournisseur. Des voies qui se chevauchent, comme la double distribution de Google Workspace, peuvent placer chaque message deux fois dans la boîte aux lettres. L'adresse de transfert continue de fonctionner lorsque la réception directe est désactivée et reste la même après une suppression et une restauration.

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 :

• Politique de réception : le comportement par défaut de la boîte aux lettres.
  • open accepte le courrier après les règles de blocage. Les résultats SPF et DKIM ne modifient pas cette politique d'admission.
  • 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.

Une règle de blocage s'applique à l'expéditeur de l'enveloppe ou à l'adresse From:. Une règle d'autorisation s'applique à l'expéditeur de l'enveloppe, ou à l'adresse From: lorsque le message porte une signature DKIM valide du domaine de cette adresse. L'en-tête From: est facile à falsifier : un From: non signé n'obtient donc jamais d'autorisation. Cela couvre le courrier transféré, pour lequel Gmail et Microsoft 365 remplacent l'expéditeur de l'enveloppe par leur propre adresse, ainsi que le courrier des services d'envoi qui utilisent une adresse de rebond distincte. Le courrier transféré dont la signature DKIM n'a pas été préservée reste évalué sur l'adresse du service de transfert.

Le courrier bloqué par une règle est conservé dans la boîte aux lettres et reste consultable. Il est classé hors de la boîte de réception et ne déclenche aucun webhook. La seule exception est une boîte aux lettres définie 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 l'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 Forward 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, ce qui permet à une intégration entrante existante de continuer à fonctionner. Les deux événements contiennent les résultats d'authentification. Vérifiez ces champs avant tout routage automatisé : la livraison en boîte de réception ne signifie pas à elle seule que l'expéditeur a été vérifié.

Conservation et suppression

Le niveau de conservation d'une boîte aux lettres détermine combien de temps vous pouvez lire les en-têtes, 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 la conservation à 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.

Par exemple, au jour 40, un message dans une boîte aux lettres à 90 jours conserve un texte extrait lisible et indexable ainsi que ses pièces jointes. Vous pouvez répondre avec un nouveau contenu, mais vous ne pouvez pas ouvrir le corps d'origine, 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 conservation étendue gardent leur expiration d'origine d'environ 31 jours ; changer de niveau ne les migre pas. Augmenter le niveau ne peut pas récupérer du contenu déjà supprimé.

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

Abaisser le niveau prend effet immédiatement sur les lectures : tout ce qui dépasse le nouveau seuil cesse d'être renvoyé sur-le-champ. 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.

Monter vers un niveau inclus dans votre forfait est accepté à tout moment, y compris pendant qu'un changement précédent est encore en cours d'application. La mise à jour en arrière-plan est indépendante de la fenêtre d'annulation de dix minutes. Un second abaissement n'est accepté qu'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, l'API renvoie E17050 ; réessayez plus tard.

Si votre forfait fixe un quota fini de stockage de boîtes aux lettres, ce quota est partagé entre toutes les boîtes aux lettres actives ou restaurables. Chaque boîte aux lettres indique sa part sous la forme size_bytes. Un forfait sans quota fini offre un stockage illimité. Lorsque l'ensemble des boîtes aux lettres atteint le quota fini, 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 conservation des messages continue. Après 30 jours, la suppression définitive efface la boîte aux lettres et ses messages restants. Une fois la suppression définitive commencé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 guidé 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.