Agent-Registrierung
Ein KI-Agent legt mit einer Anfrage sein eigenes BillionSend-Konto und Postfach an, ein Mensch übernimmt das Konto danach.
Ein KI-Agent kann sich selbst bei BillionSend registrieren, ohne dass ein Mensch dabei ist und ohne API-Schlüssel. Eine Anfrage liefert ein Postfach auf der gemeinsamen Domain und einen API-Schlüssel dafür, sodass der Agent sofort E-Mails empfangen kann. Das Konto ist nicht übernommen, bis der Mensch hinter dem Agent es übernimmt.
Registrieren
Rufen Sie POST /agent/signup mit dem Namen des Agents und der E-Mail-Adresse des Menschen dahinter auf:
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_emailist die Adresse, an die der Übernahmelink geht, und nirgendwohin sonst. Eine Adresse bei einem Wegwerf-E-Mail-Dienst oder auf einer BillionSend-Domain beantwortet die API mit422.nameist der Name des Agents: ein schlichter Name mit höchstens 60 Zeichen, ohne@, Links oder Telefonnummern. Er wird zum Namen des Kontos, bis ein Mensch es umbenennt. Ein Name, der eine Marke nachahmt, wird mit422beantwortet.usernameist optional: der Teil der Postfachadresse vor dem@, mit denselben Regeln wie beim Anlegen eines Postfachs. Wird er weggelassen, ist die Adresse zufällig.
Die Antwort ist 201 mit dem Konto, seinem Postfach und seinem Schlüssel:
{
"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 }
}
Der api_key wird nur einmal angezeigt. Es ist ein auf ein Postfach beschränkter Schlüssel: Er liest dieses eine Postfach und sonst nichts. Jede andere Route, auch das Anlegen weiterer Postfächer, antwortet mit 403 restricted_api_key.
Solange das Konto nicht übernommen ist
Ein nicht übernommenes Konto kann nur empfangen. Es hat keinen Inhaber und niemanden, der darin angemeldet ist, und es unterliegt engeren Limits als der Tarif Free:
| Nicht übernommen | Free | |
|---|---|---|
| Postfächer | 1 | 3 |
| Gesendete E-Mails pro Tag | 0 | 100 |
| Empfangene E-Mails pro Tag | 50 | 100 |
| Empfangene E-Mails pro Postfach und Stunde | 20 | 200 |
Jeder Versand, ob über die Postfach-Endpunkte, POST /emails, den Batch-Endpunkt oder SMTP, wird mit 403 team_unclaimed beantwortet. Über eines der beiden Empfangslimits hinaus erhält ein Absender bei RCPT die Antwort 452 4.2.2 und versucht es später erneut, wie bei jedem vollen Postfach. An das Postfach gesendete E-Mails kommen normal an und durchlaufen dieselben Sicherheitsschichten wie bei jedem Agent-Postfach.
Den Zustand des Kontos können Sie jederzeit mit GET /agent/status abfragen. Die Antwort lautet unclaimed mit dem Datum, an dem sich das Konto selbst löscht, oder claimed.
Das Konto übernehmen
BillionSend sendet bei der Registrierung des Agents einen Übernahmelink an human_email. Der Mensch öffnet ihn, meldet sich an oder legt sein eigenes BillionSend-Konto an und wählt Konto übernehmen.
- Der Mensch wird Inhaber des Kontos, das in den Tarif Free wechselt, und der Schlüssel des Agents funktioniert unter seinem Team weiter.
- Der Link funktioniert bis zur Frist des Kontos, und ein bereits verwendeter Link kann nicht erneut benutzt werden.
- Die Übernahme zählt auf das Teamlimit der Person, genauso wie das Anlegen eines Teams. Eine Person am Limit löscht ein Team oder upgradet und öffnet den Link dann erneut.
Ist die E-Mail nicht angekommen, kann der Agent POST /agent/claim-email aufrufen, um sie erneut zu senden. Der frühere Link funktioniert dann nicht mehr. Es werden insgesamt höchstens 5 Übernahme-E-Mails gesendet, im Abstand von zehn Minuten.
Was passiert, wenn niemand das Konto übernimmt
Ein nicht übernommenes Konto löscht sich 7 Tage nach der Registrierung selbst, mit seinem Postfach, seinen E-Mails und seinem Schlüssel, so wie beim Löschen eines Teams.
Limits
Die Registrierung ist begrenzt, damit sie nicht dazu dienen kann, die Plattform zu füllen oder Fremden zu schreiben:
| Limit | Wert |
|---|---|
| Registrierungen pro Client-Adresse | 3 pro Stunde |
| Registrierungen insgesamt | 100 pro Stunde |
Registrierungen pro human_email |
3 pro Tag |
Nicht übernommene Konten, die auf dieselbe human_email warten |
3 |
Eine abgelehnte Registrierung wird mit 429 und einem retry-after-Header beantwortet.