Registro de agentes
Deja que un agente de IA cree su propia cuenta y bandeja de entrada en BillionSend con una sola petición; una persona la reclama después.
Un agente de IA puede registrarse en BillionSend por sí solo, sin ninguna persona presente y sin clave de API. Una petición devuelve una bandeja de entrada en el dominio compartido y una clave de API para ella, así que el agente puede empezar a recibir correo al instante. La cuenta queda sin reclamar hasta que la persona responsable del agente la reclama.
Registrarse
Llama a POST /agent/signup con el nombre del agente y el email de la persona responsable:
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_emailes adonde va el enlace de reclamación, y a ningún otro sitio. Una dirección de un servicio de email desechable, o de un dominio de BillionSend, responde422.namees el nombre del agente: un nombre sencillo de hasta 60 caracteres, sin@, enlaces ni teléfonos. Pasa a ser el nombre de la cuenta hasta que una persona lo cambie. Un nombre que imita una marca responde422.usernamees opcional: la parte anterior a la@de la dirección de la bandeja, con las mismas reglas que al crear una bandeja de entrada. Si se omite, la dirección es aleatoria.
La respuesta es 201 con la cuenta, su bandeja y su clave:
{
"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 }
}
La api_key se muestra una sola vez. Es una clave restringida a una bandeja: lee esa bandeja y nada más. Cualquier otra ruta, incluida la creación de más bandejas, responde 403 restricted_api_key.
Mientras no se reclama
Una cuenta sin reclamar solo recibe. No tiene propietario ni nadie con sesión iniciada en ella, y tiene límites más estrictos que el plan Free:
| Sin reclamar | Free | |
|---|---|---|
| Bandejas de entrada | 1 | 3 |
| Emails enviados por día | 0 | 100 |
| Emails recibidos por día | 50 | 100 |
| Emails recibidos por bandeja por hora | 20 | 200 |
Todo envío, desde los endpoints de bandeja, POST /emails, el endpoint por lotes o SMTP, responde 403 team_unclaimed. Superado cualquiera de los dos límites de recepción, el remitente recibe 452 4.2.2 en RCPT y lo reintenta más tarde, como con cualquier buzón lleno. El correo enviado a la bandeja llega con normalidad y pasa por las mismas capas de seguridad que cualquier bandeja de entrada de agente.
Consulta el estado de la cuenta cuando quieras con GET /agent/status, que responde unclaimed con la fecha en que se elimina sola, o claimed.
Reclamar la cuenta
BillionSend envía un enlace de reclamación a human_email cuando el agente se registra. La persona lo abre, inicia sesión o crea su propia cuenta de BillionSend, y elige Reclamar la cuenta.
- La persona pasa a ser la propietaria de la cuenta, que pasa al plan Free, y la clave del agente sigue funcionando en su equipo.
- El enlace funciona hasta la fecha límite de la cuenta, y un enlace ya usado no se puede volver a usar.
- La reclamación suma al límite de equipos de la persona, igual que crear un equipo. Quien está en el límite elimina un equipo o cambia de plan, y abre el enlace de nuevo.
Si el email no llegó, el agente puede llamar a POST /agent/claim-email para enviarlo otra vez. El enlace anterior deja de funcionar. Se envían como máximo 5 emails de reclamación en total, con diez minutos entre uno y otro.
Qué pasa si nadie la reclama
Una cuenta sin reclamar se elimina sola 7 días después del registro, con su bandeja, su correo y su clave, del mismo modo que al eliminar un equipo.
Límites
El registro está limitado para que no sirva para llenar la plataforma ni para escribir a desconocidos:
| Límite | Valor |
|---|---|
| Registros por dirección de cliente | 3 por hora |
| Registros en total | 100 por hora |
Registros por human_email |
3 por día |
Cuentas sin reclamar a la espera de un mismo human_email |
3 |
Un registro rechazado responde 429 con la cabecera retry-after.