Pular para o conteúdo
Esc
↑↓navegar↵abrir⌘Jpré-visualizar
Nesta página

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, 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. 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.

Esta página foi útil?