Aller au contenu
Esc
↑↓naviguer↵ouvrir⌘Japerçu
Sur cette page

Boîtes de réception

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.

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, 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, ou une adresse sur le domaine partagé de BillionSend, qui n’a pas besoin de DNS.

Les SDK 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.

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.
  • 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 :

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 :

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 : 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 :

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.

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

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.

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 :

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 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.

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 :

curl "https://api.billionsend.com/inboxes/{id}/codes/latest?from=example.org&wait=30" \
  -H "Authorization: Bearer bs_..."
{
  "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.

curl -N "https://api.billionsend.com/inboxes/events?types=inbox.email.received" \
  -H "Authorization: Bearer bs_..." \
  -H "Accept: text/event-stream"
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.
  • 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.

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.

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.

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.

MCP

Les clients 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).
  • Les événements de webhook inbox.* sont sur abonnement ; inbox.thread.assigned et inbox.thread.unassigned ne sont pas envoyés.

Cette page vous a-t-elle été utile ?