---
title: Cadastro de agentes
description: Deixe um agente de IA criar a própria conta e caixa de entrada no BillionSend com uma única requisição, e uma pessoa a reivindique depois.
ai:
  exclude: true
---

Um agente de IA pode se cadastrar no BillionSend sozinho, sem ninguém presente e sem chave de API. Uma requisição devolve uma caixa de entrada no domínio compartilhado e uma chave de API para ela, e o agente já pode receber e-mails. A conta fica **não reivindicada** até que a pessoa responsável pelo agente a reivindique.

## Cadastrar

Chame `POST /agent/signup` com o nome do agente e o e-mail da pessoa responsável:

```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` é para onde vai o link de reivindicação, e para nenhum outro lugar. Um endereço de serviço de e-mail descartável, ou em um domínio do BillionSend, responde `422`.
- `name` é o nome do agente: um nome simples de até 60 caracteres, sem `@`, links ou telefones. Ele vira o nome da conta até que uma pessoa o altere. Um nome que imita uma marca responde `422`.
- `username` é opcional: a parte antes do `@` do endereço da caixa, com as mesmas regras de [criar uma caixa de entrada](/docs/pt-br/inboxes). Omitido, o endereço é aleatório.

A resposta é `201` com a conta, a caixa e a chave:

```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 }
}
```

A `api_key` aparece uma única vez. É uma [chave restrita a uma caixa](/docs/pt-br/inboxes): lê essa caixa e nada mais. Qualquer outra rota, inclusive criar mais caixas, responde `403 restricted_api_key`.

## Enquanto não reivindicada

Uma conta não reivindicada só recebe. Ela não tem proprietário nem ninguém conectado a ela, e tem limites mais apertados que o plano Free:

| | Não reivindicada | Free |
| --- | --- | --- |
| Caixas de entrada | 1 | 3 |
| E-mails enviados por dia | 0 | 100 |
| E-mails recebidos por dia | 50 | 100 |
| E-mails recebidos por caixa por hora | 20 | 200 |

Todo envio, pelos endpoints de caixa, `POST /emails`, o endpoint em lote ou SMTP, responde `403 team_unclaimed`. Passado qualquer um dos limites de recebimento, o remetente recebe `452 4.2.2` no RCPT e tenta de novo mais tarde, como com qualquer caixa cheia. Os e-mails enviados para a caixa chegam normalmente e passam pelas mesmas [camadas de segurança](/docs/pt-br/agent-safety) de qualquer caixa de agente.

Consulte o estado da conta quando quiser com `GET /agent/status`, que responde `unclaimed` com a data em que ela se exclui, ou `claimed`.

## Reivindicar a conta

O BillionSend envia um link de reivindicação para `human_email` quando o agente se cadastra. A pessoa abre o link, entra ou cria a própria conta no BillionSend e escolhe **Reivindicar a conta**.

- A pessoa passa a ser a proprietária da conta, que vai para o plano Free, e a chave do agente continua funcionando na equipe dela.
- O link vale até o prazo da conta, e um link já usado não pode ser usado de novo.
- Reivindicar conta no limite de equipes da pessoa, como criar uma equipe. Quem está no limite exclui uma equipe ou faz upgrade e abre o link de novo.

Se o e-mail não chegou, o agente pode chamar `POST /agent/claim-email` para enviá-lo de novo. O link anterior deixa de funcionar. No máximo 5 e-mails de reivindicação são enviados no total, com dez minutos de intervalo.

## Se ninguém reivindicar

Uma conta não reivindicada se exclui 7 dias após o cadastro, com a caixa, as mensagens e a chave, do mesmo jeito que excluir uma equipe.

## Limites

O cadastro é limitado para não servir para encher a plataforma nem para escrever a desconhecidos:

| Limite | Valor |
| --- | --- |
| Cadastros por endereço de cliente | 3 por hora |
| Cadastros no total | 100 por hora |
| Cadastros por `human_email` | 3 por dia |
| Contas não reivindicadas esperando um mesmo `human_email` | 3 |

Um cadastro recusado responde `429` com o cabeçalho `retry-after`.
