Skip to content
Esc
↑↓navigate↵open⌘Jpreview
On this page

Agent signup

Let an AI agent create its own BillionSend account and inbox with one request, with a person claiming the account afterwards.

An AI agent can sign up for BillionSend on its own, with no person present and no API key. One request returns an inbox on the shared domain and an API key for it, so the agent can start receiving mail at once. The account is unclaimed until the person behind the agent claims it.

Sign up

Call POST /agent/signup with the agent’s name and the email address of the person behind it:

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 is where the claim link goes, and nowhere else. An address at a disposable-email service, or on a BillionSend domain, answers 422.
  • name is the agent’s name: a plain name of at most 60 characters, without @, links or phone numbers. It becomes the account’s name until a person renames it. A name that imitates a brand answers 422.
  • username is optional: the part before the @ of the inbox address, under the same rules as creating an inbox. Left out, the address is random.

The response is 201 with the account, its inbox and its key:

{
  "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 }
}

The api_key is shown once. It is an inbox-scoped key: it reads the one inbox and nothing else. Every other route, including creating more inboxes, answers 403 restricted_api_key.

While unclaimed

An unclaimed account only receives. It has no owner and no one signed in to it, and it is held to tighter limits than the Free plan:

Unclaimed Free
Inboxes 1 3
Emails sent per day 0 100
Emails received per day 50 100
Emails received per inbox per hour 20 200

Every send, from the inbox endpoints, POST /emails, the batch endpoint or SMTP, answers 403 team_unclaimed. Past either receiving limit, a sender is answered 452 4.2.2 at RCPT and retries later, as with any full mailbox. Mail sent to the inbox arrives normally and goes through the same safety layers as any agent inbox.

Ask for the account’s state at any time with GET /agent/status, which answers unclaimed with the date it deletes itself, or claimed.

Claim the account

BillionSend emails a claim link to human_email when the agent signs up. The person opens it, signs in or creates their own BillionSend account, and chooses Claim the account.

  • The person becomes the owner of the account, which moves to the Free plan, and the agent’s key keeps working under their team.
  • The link works until the account’s deadline, and a claimed link cannot be used again.
  • Claiming counts against the person’s team limit, like creating a team does. A person at the limit deletes a team or upgrades, then opens the link again.

If the email did not arrive, the agent can call POST /agent/claim-email to send it again. The earlier link stops working. At most 5 claim emails are sent in all, ten minutes apart.

What happens if nobody claims it

An unclaimed account deletes itself 7 days after signup, with its inbox, its mail and its key, the same way deleting a team does.

Limits

Signup is limited so it cannot be used to fill the platform or to write to strangers:

Limit Value
Signups per client address 3 per hour
Signups in all 100 per hour
Signups per human_email 3 per day
Unclaimed accounts waiting on one human_email 3

A refused signup answers 429 with a retry-after header.

Was this page helpful?