---
title: Agent signup
description: 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:

```sh
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](/docs/inboxes). Left out, the address is random.

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

```json
{
  "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](/docs/inboxes): 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](/docs/agent-safety) 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.
