Cadastro de agentes
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.
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:
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, responde422.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 responde422.usernameé opcional: a parte antes do@do endereço da caixa, com as mesmas regras de criar uma caixa de entrada. Omitido, o endereço é aleatório.
A resposta é 201 com a conta, a caixa e a chave:
{
"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: 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 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.