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

Inscription des agents

Laissez un agent IA créer lui-même son compte BillionSend et sa boîte de réception en une requête, puis une personne revendique le compte.

Un agent IA peut s’inscrire seul à BillionSend, sans personne à ses côtés et sans clé API. Une requête renvoie une boîte de réception sur le domaine partagé et une clé API pour elle, et l’agent peut recevoir des e-mails aussitôt. Le compte reste non revendiqué jusqu’à ce que la personne derrière l’agent le revendique.

S’inscrire

Appelez POST /agent/signup avec le nom de l’agent et l’adresse e-mail de la personne qui se trouve derrière :

curl -X POST "https://api.billionsend.com/agent/signup" \
  -H "Content-Type: application/json" \
  -d '{
    "human_email": "ana@example.com",
    "name": "Research helper",
    "username": "research-helper"
  }'
  • human_email est l’adresse où part le lien de revendication, et nulle part ailleurs. Une adresse d’un service d’e-mail jetable, ou d’un domaine BillionSend, répond 422.
  • name est le nom de l’agent : un nom simple de 60 caractères au plus, sans @, sans lien ni numéro de téléphone. Il devient le nom du compte jusqu’à ce qu’une personne le renomme. Un nom qui imite une marque répond 422.
  • username est facultatif : la partie avant le @ de l’adresse de la boîte, soumise aux mêmes règles que la création d’une boîte de réception. S’il est omis, l’adresse est aléatoire.

La réponse est 201, avec le compte, sa boîte et sa clé :

{
  "object": "agent_signup",
  "status": "unclaimed",
  "api_key": "bs_...",
  "inbox": { "id": "...", "email_address": "research-helper@team-k3m9x2.example.com", "...": "..." },
  "claim": { "email": "ana@example.com", "expires_at": "2026-11-23T10:00:00.000Z" },
  "limits": { "receive_only": true, "inboxes": 1, "emails_per_day": 0, "received_per_day": 50, "received_per_inbox_per_hour": 20 }
}

L’api_key n’est affichée qu’une seule fois. C’est une clé limitée à une boîte : elle lit cette boîte et rien d’autre. Toutes les autres routes, y compris la création d’autres boîtes, répondent 403 restricted_api_key.

Tant que le compte n’est pas revendiqué

Un compte non revendiqué ne fait que recevoir. Il n’a pas de propriétaire et personne n’y est connecté, et il est soumis à des limites plus strictes que le forfait Free :

Non revendiqué Free
Boîtes de réception 1 3
E-mails envoyés par jour 0 100
E-mails reçus par jour 50 100
E-mails reçus par boîte et par heure 20 200

Tout envoi, par les endpoints de la boîte, POST /emails, l’endpoint de lot ou SMTP, répond 403 team_unclaimed. Au-delà de l’une ou l’autre des limites de réception, l’expéditeur reçoit 452 4.2.2 au RCPT et réessaie plus tard, comme avec toute boîte pleine. Les e-mails envoyés à la boîte arrivent normalement et passent par les mêmes couches de sécurité que toute boîte d’agent.

Demandez l’état du compte à tout moment avec GET /agent/status, qui répond unclaimed avec la date de sa suppression automatique, ou claimed.

Revendiquer le compte

BillionSend envoie un lien de revendication à human_email lors de l’inscription de l’agent. La personne l’ouvre, se connecte ou crée son propre compte BillionSend, puis choisit Réclamer le compte.

  • La personne devient propriétaire du compte, qui passe au forfait Free, et la clé de l’agent continue de fonctionner au sein de son équipe.
  • Le lien fonctionne jusqu’à l’échéance du compte, et un lien déjà utilisé ne peut pas servir une seconde fois.
  • La revendication compte dans la limite d’équipes de la personne, comme la création d’une équipe. Une personne qui a atteint la limite supprime une équipe ou passe à un forfait supérieur, puis rouvre le lien.

Si l’e-mail n’est pas arrivé, l’agent peut appeler POST /agent/claim-email pour le renvoyer. Le lien précédent cesse de fonctionner. Au plus 5 e-mails de revendication sont envoyés en tout, à dix minutes d’intervalle.

Que se passe-t-il si personne ne revendique le compte

Un compte non revendiqué se supprime 7 jours après l’inscription, avec sa boîte, ses e-mails et sa clé, de la même façon que la suppression d’une équipe.

Limites

L’inscription est limitée pour qu’elle ne serve ni à saturer la plateforme ni à écrire à des inconnus :

Limite Valeur
Inscriptions par adresse client 3 par heure
Inscriptions au total 100 par heure
Inscriptions par human_email 3 par jour
Comptes non revendiqués en attente pour un même human_email 3

Une inscription refusée répond 429 avec un en-tête retry-after.

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