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

Bases de l'API

URL de base, permissions des clés API, liste des erreurs, limites de débit, clés d'idempotence et pagination de l'API BillionSend.

Les pages de points d’accès de la référence de l’API sont générées à partir des définitions de routes de l’API. La spécification OpenAPI 3.1 est la même source, dans un seul fichier JSON.

L’API est compatible avec l’API Resend : mêmes chemins, mêmes formats de requête et d’erreur. Appelez-la depuis les SDK BillionSend ou en HTTP brut.

URL de base

https://api.billionsend.com

Authentification

Envoyez dans chaque requête une clé API créée sous Clés API dans le tableau de bord :

Authorization: Bearer bs_...

Une clé absente ou mal formée répond 401 missing_api_key, une clé incorrecte 401 invalid_api_key.

Une clé a un niveau de permission :

  • Accès complet peut utiliser tous les points d’accès.
  • Envoi uniquement ne peut qu’envoyer. Tout ce qui est en dehors de /emails répond 403 restricted_api_key, de même que GET /emails, GET /emails/{id}, GET /emails/metrics, DELETE /emails/{id} et tous les points d’accès /emails/receiving, car ils renvoient du contenu stocké.

Une clé peut aussi être limitée à un domaine ou à une boîte de réception. Une clé limitée à un domaine travaille à l’intérieur de ce domaine : elle n’envoie que depuis lui, ne lit que ses e-mails, ne voit et ne modifie que lui sous /domains, et répond 403 restricted_api_key pour tout ce qui appartient à l’équipe entière (webhooks, listes de suppression, templates, propriétés de contact, /usage, /deliverability, vérifications, POST /domains) ; voir Clés API. Une clé que vous créez avec l’API n’est jamais plus large que la clé qui l’a créée.

Une équipe peut avoir 25 clés actives. Les actions qui exigent une clé créée par un propriétaire ou un administrateur sont listées sous Rôles dans l’équipe.

Erreurs

Chaque erreur a cette forme :

{ "statusCode": 422, "name": "validation_error", "message": "..." }
Statut et nom Signification
400 invalid_parameter Le corps n’est pas du JSON valide.
401 missing_api_key / invalid_api_key Pas de clé, ou une clé incorrecte.
403 restricted_api_key La permission ou la portée de la clé ne l’autorise pas.
403 forbidden Votre rôle ou votre clé n’autorise pas cette action.
403 plan_limit_reached Vous avez atteint une limite de votre forfait. Voir Forfaits et limites.
403 sending_paused L’envoi est suspendu parce que votre taux de rebonds ou de plaintes est trop élevé.
404 not_found Le point d’accès, ou ce que vous avez demandé, n’existe pas.
409 invalid_idempotent_request La clé d’idempotence a été utilisée avec une charge utile différente.
415 Le corps n’est pas application/json.
422 validation_error La requête n’est pas valide. Le message en donne la raison.
422 all_recipients_suppressed Tous les destinataires sont dans la liste de suppression ou se sont désinscrits. Voir Listes de suppression.
429 rate_limit_exceeded Trop de requêtes.
429 daily_quota_exceeded / monthly_quota_exceeded Le quota d’envoi de votre forfait est épuisé. Voir Forfaits et limites.
503 service_unavailable Le stockage des statistiques n’a pas répondu. L’envoi n’est pas affecté.

Chaque 429 porte un en-tête retry-after : le nombre de secondes à attendre.

Chaque réponse, d’erreur ou non, porte un en-tête x-request-id : l’identifiant de la requête, le même que celui qu’elle a sur la page Journaux du tableau de bord. Indiquez-le quand vous nous interrogez sur une requête.

Un destinataire dont le domaine ne pourra jamais recevoir de courrier, comme x@example.com, x@foo.test ou x@gmail.con, est refusé avec 422 validation_error. Il en va de même pour un nouveau contact à une telle adresse. Pour tester sans écrire à personne, envoyez à success@simulator.amazonses.com.

La réception, les boîtes de réception et la sécurité des agents ajoutent leurs propres erreurs, que ces pages listent.

Limites de débit

Chaque clé API peut faire 600 requêtes par minute, et les clés d’une équipe 3 000 en tout. Au-delà de la limite, vous recevez 429 rate_limit_exceeded et un en-tête retry-after. Plus de 20 authentifications échouées par minute depuis une même adresse IP sont refusées de la même façon.

Idempotence

POST /emails et POST /emails/batch acceptent un en-tête Idempotency-Key de 1 à 256 caractères. C’est aussi le cas des réponses, des transferts et des envois de brouillons des boîtes de réception, ainsi que des réponses et des transferts d’e-mails reçus. Réessayez avec la même clé et la même charge utile : vous obtenez la réponse d’origine au lieu d’un second e-mail. La même clé avec une charge utile différente répond 409.

Pagination

Les points d’accès de liste acceptent limit (1 à 100, 20 par défaut) et les curseurs after et before, chacun étant l’identifiant d’un élément d’une page précédente. La réponse contient has_more. Les listes sont triées du plus récent au plus ancien :

  • after prend le dernier identifiant d’une page et renvoie des éléments plus anciens.
  • before prend le premier identifiant et renvoie des éléments plus récents.

Pour rattraper les nouveautés, passez dans before l’identifiant le plus récent que vous avez enregistré.

Quelques listes suivent un autre ordre, que leurs pages de référence indiquent : les fils d’une boîte de réception (activité la plus récente en premier), les e-mails d’un fil (les plus anciens en premier), et les thématiques et les libellés (les plus anciens en premier, tous d’un coup). Un curseur qui ne correspond à aucun élément répond 422 validation_error (404 sous /inboxes).

Règles utiles à connaître

  • Pièces jointes : seul content en base64 intégré est accepté. Une URL path distante répond 422. Les pièces jointes totalisent jusqu’à 10 MiB par e-mail, et l’e-mail entier doit rester sous 40 MB. Les programmes et les scripts (.exe, .js, .bat et assimilés, y compris dans un ZIP) sont toujours refusés. Sur une nouvelle équipe, certains types à risque, comme les archives, les pages web et les fichiers Office avec macros, sont acceptés mais attendent une revue avant d’être envoyés.
  • Contacts : ils appartiennent à l’équipe. Il n’y a pas d’audiences : les points d’accès d’audience fonctionnent comme des alias des segments.
  • Désinscriptions : elles appartiennent au domaine d’envoi. Voir Désinscriptions.
  • Destinataires : to, cc et bcc ensemble acceptent jusqu’à 50 adresses, chacune étant une seule boîte mail. Un envoi dont toutes les adresses to sont dans la liste de suppression répond 422 all_recipients_suppressed.
  • En-têtes : ils sont soumis à une liste autorisée : tout nom X-* (sauf X-SES-* et X-BillionSend-*), les en-têtes de fil de discussion et de priorité, et la paire List-Unsubscribe. Tout autre en-tête répond 422.
  • Objets : ils peuvent compter jusqu’à 998 caractères.
  • Points d’accès supplémentaires : GET /usage (forfait, limites et consommation), DELETE /emails/{id} et GET /emails/metrics (Statistiques).
  • Contacts en masse : POST /contacts/batch crée et POST /contacts/batch/remove supprime jusqu’à 1 000 contacts en une seule requête. include=properties,topics sur les listes de contacts ajoute les propriétés et les thématiques de chaque contact.
  • Suppressions en masse : elles acceptent jusqu’à 1 000 adresses par requête.
  • Statuts supplémentaires : les campagnes peuvent être canceled.
  • Réception et boîtes de réception : elles sont en bêta, avec de l’interrogation longue (long-polling) et un flux d’événements en direct pour les nouveaux e-mails. Voir Réception et Boîtes de réception.
  • Réglages non pris en charge : ils sont rejetés avec 422 au lieu d’être ignorés en silence.

Liens de téléchargement signés

Les e-mails reçus portent des liens de téléchargement du message brut et de ses pièces jointes. Ce sont de simples URL GET qui n’exigent aucune clé API, valent une heure et répondent 403 une fois expirées. Demandez de nouveau à l’API un lien à jour. Voir Réception.

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