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

Réception

Recevez des e-mails sur votre propre domaine et lisez-les via l'API, les webhooks et le tableau de bord.

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

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

Configuration

  1. Choisissez un nom qui ne reçoit pas encore de courrier, par exemple inbound.example.com. L’enregistrement MX prend en charge toutes les adresses du nom sur lequel il est publié ; vos boîtes mail sur example.com restent donc chez votre fournisseur actuel.

  2. Ajoutez et vérifiez ce nom exact sous Domaines, comme pour l’envoi. Vérifier example.com ne couvre pas ses sous-domaines.

  3. Activez la réception : ouvrez le domaine et activez Activer la réception, ou appelez l’API :

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

    Un nom ne peut recevoir que dans une seule équipe ; un nom sur lequel une autre équipe reçoit déjà répond 409.

  4. Publiez les deux enregistrements MX affichés dans les enregistrements du domaine, chez votre fournisseur DNS :

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

    Chacun est un serveur de messagerie distinct. Quand les deux sont publiés, un expéditeur qui trouve l’un d’eux hors service réessaie sur l’autre en quelques secondes ; publiez donc les deux avec la même priorité. Chaque ligne est vérifiée dès qu’aucun autre enregistrement MX de ce nom n’a un numéro de priorité plus bas.

  5. Choisissez les adresses : créez une boîte de réception pour chaque adresse, ou activez Catch-all sur la page du domaine. Sans l’un ni l’autre, le domaine refuse tout le courrier.

  6. Envoyez un test depuis n’importe quelle boîte mail. Il apparaît sous Boîtes de réception → Tous les e-mails reçus en quelques secondes.

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

Quelles adresses reçoivent

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

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

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

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

Filtrage et limites

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

Interrupteur Activé Désactivé
Rejeter le spam au-dessus du score 5 (activé par défaut) Un e-mail dont le score de spam est de 5 ou plus (sur une échelle de 0 à 10) est refusé avec 554 5.7.1 ; rien n’est stocké. Le spam est stocké : dans le dossier spam d’une boîte de réception, simplement signalé sur une adresse catch-all.
Retirer les pièces jointes de plus de 10 MB (désactivé par défaut) Chaque pièce jointe plus grande est remplacée par une courte note <fichier>.removed.txt indiquant ce qui a été retiré. Les pièces jointes sont stockées telles qu’elles sont arrivées.
Conserver le .eml brut 30 jours (activé par défaut) Le contenu reste pendant votre durée de conservation. Le contenu (texte, HTML, en-têtes, message brut, pièces jointes) est supprimé après 1 jour. Les métadonnées et les webhooks ne changent pas.
Limite Free Starter, Pro, Scale
Taille du message 10 MB 40 MB
Catch-all Non Oui
E-mails reçus 100 par jour UTC 2 fois le volume mensuel de votre forfait, chaque mois
Au-delà Différé jusqu’à minuit UTC Différé jusqu’au renouvellement de votre volume
Conservation 30 jours 30 jours
  • La taille compte le message stocké en entier, après retrait des pièces jointes. Le Base64 alourdit les pièces jointes d’environ un tiers : sur 40 MB, il tient donc à peu près 30 MB de fichiers. Un message plus grand est refusé avec 552 5.3.4.
  • Un e-mail reçu compte une fois par message et par équipe, dans sa propre limite. Il n’utilise jamais votre volume d’envoi, et l’envoi n’utilise jamais votre limite de réception.
  • Quand la limite est atteinte, le serveur de l’expéditeur reçoit l’ordre de réessayer plus tard (452 4.2.2) et réessaie pendant plusieurs jours, couramment jusqu’à cinq : le message arrive donc dès qu’il y a de la place. Un e-mail encore différé quand le serveur de l’expéditeur abandonne est renvoyé à son expéditeur.
  • Quand la conservation prend fin, html, text, headers et raw valent null, attachments est vide et les liens de téléchargement cessent de fonctionner. L’expéditeur, les destinataires et l’objet restent.

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

Lire les e-mails reçus

Utilisez emails.receiving dans les SDK, ou du HTTP brut. Ces points d’accès exigent une clé API à accès complet ; une clé réservée à l’envoi reçoit 403 restricted_api_key. Une clé restreinte à un domaine ne lit que les e-mails de ce domaine, et une clé restreinte à une boîte de réception que ceux de cette boîte.

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

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

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

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

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

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

Attendre de nouveaux e-mails

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

curl "https://api.billionsend.com/emails/receiving?inbox_id=7eeb9517-aed7-40d7-ad65-500be42ed147&from=example.org&wait=30" \
  -H "Authorization: Bearer bs_..."
  • Sans before ni since, les e-mails des 60 dernières secondes comptent : un message arrivé juste avant l’appel n’est donc pas manqué.
  • La réponse ajoute held : les messages correspondants retenus depuis, avec leur id et leur motif, pour que l’agent sache qu’il doit arrêter d’attendre et prévenir une personne.
  • Une équipe peut avoir 20 attentes simultanées sur chaque processus de l’API ; la suivante répond 429 too_many_waits.
  • Une attente interroge la base de données à l’arrivée d’un e-mail (les mêmes événements que le flux d’événements des boîtes de réception), et non sur un minuteur.

Résultats d’authentification

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

Spam, virus et confiance

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

Contenu

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

Texte des pièces jointes

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

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

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

Téléchargements

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

Répondre et transférer

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

curl -X POST "https://api.billionsend.com/emails/receiving/{id}/reply" \
  -H "Authorization: Bearer bs_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1042-reply" \
  -d '{ "text": "Merci, nous nous en occupons." }'
  • Répondre accepte text ou html, subject, cc, bcc et reply_all. La réponse part vers le Reply-To du message, ou à défaut vers son expéditeur.
  • Transférer accepte to, cc, bcc, une note, subject et mode : inline (par défaut) cite l’original, attachment le joint sous le nom forwarded_message.eml.
  • from est n’importe quelle adresse d’un domaine vérifié de votre équipe ; par défaut, l’adresse de la boîte de réception où le message est arrivé. requires_approval: true retient l’envoi pour une personne.
  • Les deux comptent comme des envois ordinaires, avec jusqu’à 10 MiB de pièces jointes.

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

Webhook

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

Ce que voit l’expéditeur

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

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

Tableau de bord

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

MCP

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

Traiter les e-mails reçus comme non fiables

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

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