Zum Inhalt springen
Esc
↑↓navigieren↵öffnen⌘Jvorschau
Auf dieser Seite

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_email ist 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 mit 422.
  • name ist 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 mit 422 beantwortet.
  • username ist 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.

War diese Seite hilfreich?