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

Postfächer

E-Mail-Adressen, die E-Mails in Threads ordnen und von derselben Adresse antworten, für einen KI-Agent oder für Menschen.

Ein Postfach ist eine E-Mail-Adresse, die E-Mails in Threads empfängt und von derselben Adresse sendet. Geben Sie eines einem KI-Agent, der es über die API, Webhooks oder den MCP-Server liest, oder Menschen, die es im Dashboard lesen. Ein Postfach ist eine Adresse auf einer Ihrer empfangenden Domains oder eine Adresse auf der gemeinsamen Domain von BillionSend, die kein DNS braucht.

Die SDKs decken jeden Postfach-Endpunkt als inboxes.* ab, einschließlich der Sicherheitsregeln, der Quarantäne, der Freigaben und des Live-Event-Streams.

Agent oder Menschen

Jedes Postfach hat einen kind, der beim Anlegen gewählt wird und sich nie ändert. Der Typ legt die Standardwerte der Sicherheitseinstellungen fest.

Einstellung Agent Menschen
accept_from verified anyone
screening an aus
extract_codes an an
send_policy reply_only open (reply_only auf der gemeinsamen Domain)
require_approval aus aus
private_codes an aus
send_cap 200 (50 auf der gemeinsamen Domain) keines (50 auf der gemeinsamen Domain)
  • agent ist der Standard, wenn kind fehlt. E-Mails von Absendern, für die ihre Domain nicht bürgt, warten in Quarantäne, E-Mails anderer externer Absender werden auf Prompt-Injection geprüft, und der Agent antwortet innerhalb bestehender Threads: Eine neue Unterhaltung, die er beginnt, wird zu einem Entwurf, der auf einen Menschen wartet. Siehe Agent-Sicherheit.
  • human ist für Menschen, die im Dashboard lesen: Die E-Mails aller werden zugestellt (eine fehlgeschlagene Authentifizierung landet im Ordner spam), und nichts wird geprüft.

E-Mails mit einem Virus kommen in jedem Postfach in Quarantäne.

Ein Postfach anlegen

Öffnen Sie im Dashboard Postfächer und wählen Sie Postfach erstellen. Oder rufen Sie die API auf:

curl -X POST "https://api.billionsend.com/inboxes" \
  -H "Authorization: Bearer bs_..." \
  -H "Content-Type: application/json" \
  -d '{
    "email_address": "orders@inbound.example.com",
    "name": "Orders agent",
    "kind": "agent"
  }'

Mit dem Node.js-SDK:

import { BillionSend } from "@billionsend/node";

const bs = new BillionSend(); // reads BILLIONSEND_API_KEY

const { data, error } = await bs.inboxes.create({
  email_address: "orders@inbound.example.com",
  name: "Orders agent",
  kind: "agent",
});

Die Antwort (201) ist das ganze Postfach: id, name, email_address, domain_id, kind, shared, expires_at, unread (Threads mit einer ungelesenen Nachricht), drafts, quarantined, pending_approval und mehr.

Feld Regeln
email_address Eine Adresse auf einer verifizierten Domain Ihres Teams, die E-Mails empfängt. In Kleinbuchstaben; der Teil vor @ nimmt bis zu 64 Buchstaben, Ziffern und . _ % + - auf. Sie lässt sich später nicht ändern. Weglassen für eine Adresse auf der gemeinsamen Domain.
username Ohne email_address der Teil vor @ auf der gemeinsamen Domain; wird er weggelassen, ist die Adresse zufällig. Mit der domain_id einer Ihrer eigenen Domains ist es der Teil vor @ dort.
domain_id Eine Zeile aus GET /domains: die gemeinsame Subdomain Ihres Teams (shared: true) oder eine Ihrer verifizierten Domains.
name 1 bis 320 Zeichen; ohne Angabe die Adresse.
from_name Anzeigename der E-Mails, die das Postfach sendet, bis zu 78 Zeichen: ein schlichter Name, ohne @, :, <, >, Zeilenumbrüche, Links oder Telefonnummern.
kind agent (Standard) oder human.
expires_in Wann das Postfach abläuft, etwa 1h, 24h oder 7d; ohne Angabe nie.
safety Beliebige der Sicherheitseinstellungen.
forwarding true fügt eine receiving_address auf der gemeinsamen Domain hinzu, um ein Postfach, das Sie anderswo behalten, in das Postfach weiterzuleiten.
Antwort Wann
409 validation_error Ein anderes Postfach nutzt die Adresse bereits. Es wird kein anderer Name für Sie gewählt.
403 validation_error Das Postfachlimit Ihres Tarifs ist erreicht.
429 rate_limit_exceeded In der letzten Stunde wurden zu viele Postfächer angelegt, oder die Namensprüfung der gemeinsamen Domain hat das heutige Limit erreicht. retry-after sagt, wann Sie es erneut versuchen können.
422 validation_error Die Domain ist nicht verifiziert oder empfängt keine E-Mails, ein username verletzt eine Regel oder ist reserviert, oder eine Einstellung verletzt eine Regel.
503 name_review_unavailable Ein Name auf der gemeinsamen Domain konnte gerade nicht geprüft werden. Versuchen Sie es in Kürze erneut.

Die anderen Aufrufe:

  • GET /inboxes listet Postfächer, neueste zuerst (?kind=agent oder ?kind=human grenzt ein).
  • GET /inboxes/{id} liest eines. Jede {id} in einem Pfad /inboxes/{id}/… nimmt die ID des Postfachs oder seine E-Mail-Adresse.
  • PATCH /inboxes/{id} ändert name, from_name oder expires_in.
  • DELETE /inboxes/{id} löscht das Postfach mit seinen Threads, Entwürfen und Labels und widerruft seine API-Schlüssel. Eine Nachricht, die auch ein anderes Postfach oder eine Catch-all-Adresse erreicht hat, bleibt dort.

Adressen

Ihre eigene Domain

Ein Postfach auf Ihrer eigenen Domain braucht eine Domain, die E-Mails empfängt: verifiziert, mit eingeschaltetem Empfang und veröffentlichtem MX-Eintrag. Jede Nachricht geht nach der Adresse, an die der Server des Absenders zugestellt hat:

  1. an das Postfach mit genau dieser Adresse;
  2. sonst bei name+tag@ an das Postfach von name@;
  3. sonst, wenn das Catch-all der Domain an ist, nach Alle empfangenen ohne Postfach; bei ausgeschaltetem Catch-all wird die Adresse abgelehnt (550 5.1.1).

E-Mails, die von der Adresse eines Postfachs gesendet werden, folgen auf jedem Weg den Regeln des Postfachs: POST /emails, dem Batch-Endpunkt, dem SMTP-Relay und MCP. Geben Sie einem Postfach eine Adresse, von der Ihre App nicht bereits sendet.

Gemeinsame Domain

Ein Postfach auf der gemeinsamen Domain braucht kein DNS. Jedes Team erhält eine eigene Subdomain auf der gemeinsamen Domain von BillionSend, benannt nach dem Team. Lassen Sie email_address weg oder senden Sie die ID der gemeinsamen Zeile als domain_id, dann benennt username die Adresse:

curl -X POST "https://api.billionsend.com/inboxes" \
  -H "Authorization: Bearer bs_..." \
  -H "Content-Type: application/json" \
  -d '{ "username": "orders", "name": "Orders agent" }'

Ohne username ist die Adresse zufällig. Ein Benutzername wird abgelehnt (422), wenn er reserviert ist (postmaster, abuse, admin, security, support, noreply, no-reply, billing, hostmaster, webmaster, mailer-daemon, root), mit fwd- beginnt oder wie eine bekannte Marke aussieht. Ein bereits vergebener wird mit 409 beantwortet.

Namensprüfung. Ein gewählter Benutzername, ein from_name und die Subdomain des Teams werden vor der Veröffentlichung geprüft, um Namen zu stoppen, die sich als Marke, Bank, Behörde oder offizielle Rolle ausgeben. Ein abgelehnter Name wird mit 422 beantwortet. Solange die Prüfung nicht antworten kann, erhalten Sie 503 name_review_unavailable; die Subdomain eines neuen Teams wird wiederholt, bis sie besteht, und nach 24 Stunden erhält das Team team- und sechs zufällige Zeichen. Ab 20 abgelehnten Namen oder 200 Prüfungen an einem UTC-Tag lautet die Antwort 429 bis Mitternacht UTC.

Gemeinsame Adressen folgen eigenen Regeln, da die Domain allen Teams gehört:

  • Sie bestehen, bis sie gelöscht werden, sofern expires_in nichts anderes sagt, und zählen auf das Postfachlimit Ihres Tarifs. Eines, das 90 Tage lang niemand genutzt hat, wird gelöscht.
  • Im Tarif Free und bei jeder Adresse, deren Name wie eine bekannte Marke aussieht, antworten sie nur innerhalb ihrer eigenen Threads, an Absender, für die ihre Domain gebürgt hat, und an die Anmeldeadressen Ihrer Teammitglieder. In einem kostenpflichtigen Tarif beginnen Menschen von ihnen aus Unterhaltungen, und ein Agent tut das, wenn seine send_policy open ist und Ihr Team seine ersten Sendungen hinter sich hat; sonst warten seine neuen Unterhaltungen als Entwürfe auf einen Menschen. Jede Nachricht an einen Fremden wird vor dem Versand auf Phishing geprüft. Eine Ablehnung wird mit 403 inbox_send_policy beantwortet.
  • Jede E-Mail geht an höchstens 10 Empfänger. Ein Postfach sendet an höchstens 50 Empfänger pro Tag (send_cap von 1 bis 50), und alle gemeinsamen Adressen Ihres Teams zusammen erreichen 1.000 Empfänger pro UTC-Tag; darüber 429 inbox_send_cap_reached.
  • from muss genau die Adresse des Postfachs sein, und die E-Mail darf weder scheduled_at, reply_to, Anhänge noch eigene Header tragen (422). POST /emails/batch, Newsletter-Versände und das SMTP-Relay lehnen eine gemeinsame Adresse immer ab.
  • forward_to nimmt nur Anmeldeadressen von Mitgliedern an.

E-Mails an postmaster@ und abuse@ auf der gemeinsamen Domain gehen an BillionSend, nie an ein Postfach.

Ein Postfach in ein Postfach weiterleiten

forwarding: true ist für eine Adresse, deren E-Mails anderswo liegen, etwa ein Google-Workspace-Postfach. Das Postfach erhält eine receiving_address, eine zufällige Adresse auf der gemeinsamen Subdomain Ihres Teams: Leiten Sie das Postfach dorthin weiter, und das Postfach empfängt die E-Mails und antwortet von seiner eigenen Adresse. Die Domain muss dann nur für den Versand verifiziert sein.

Ablauf

expires_in ist eine Zahl gefolgt von h oder d, von 1h bis 365d; ohne Angabe läuft das Postfach nie ab. Ein PATCH mit neuem expires_in zählt ab diesem Moment, und null entfernt den Ablauf. expires_at zeigt, wann er endet.

Bei expires_at stoppt das Postfach: E-Mails an es werden abgelehnt (550 5.1.1), Lesezugriffe antworten mit 404, und seine API-Schlüssel funktionieren nicht mehr. Innerhalb einer Stunde wird es gelöscht, mit einem Webhook inbox.expired, gefolgt von inbox.deleted. Den Ablauf zu ändern erfordert die Rolle Entwickler, Admin oder Inhaber.

Threads

Jede Nachricht eines Postfachs gehört zu einem Thread, und ein Thread enthält beide Richtungen: was das Postfach empfangen und was es gesendet hat.

  • Wie Antworten ihren Thread finden. E-Mails, die das Postfach sendet, tragen ein Thread-Token in ihrem Header References. Eine Antwort landet im selben Thread, wenn sie dieses Token trägt, wenn ihr In-Reply-To eine vom Postfach gesendete Nachricht nennt oder wenn sie auf eine frühere Nachricht des Threads verweist. Betreffs führen nie Threads zusammen.
  • Ordner. Ein Thread liegt in einem Ordner: inbox, archive, spam, sent oder trash. Neue E-Mails holen einen archivierten oder gesendeten Thread zurück nach inbox. DELETE verschiebt einen Thread nach trash, der nach 30 Tagen geleert wird.
  • Lesestatus. Ein PATCH mit read markiert den ganzen Thread. Zurückgehaltene E-Mails machen einen Thread nie ungelesen. In einem Postfach für Menschen markiert das Öffnen eines Threads ihn als gelesen; in einem Agent-Postfach gehört der Lesestatus Ihrem Agent.
  • Labels. Bis zu 100 pro Postfach, Namen mit 1 bis 64 Zeichen, Farben als #RRGGBB.
Aufruf Bewirkt
GET /inboxes/{id}/threads Threads, letzte Aktivität zuerst. Filter: folders, labels, read, include_quarantined.
GET /inboxes/{id}/threads/search Dieselben Filter plus query ("exact phrase" und -excluded funktionieren), from, to, cc, bcc, has_attachment, start_date, end_date.
GET /inboxes/{id}/threads/{thread_id} Ein Thread.
PATCH /inboxes/{id}/threads/{thread_id} read oder folder setzen.
POST / PUT / DELETE …/threads/{thread_id}/labels Labels hinzufügen, ersetzen oder entfernen.
DELETE /inboxes/{id}/threads/{thread_id} Verschiebt den Thread in den Papierkorb.
GET /inboxes/{id}/threads/{thread_id}/emails Seine E-Mails, älteste zuerst.

Die Suche findet ganze Wörter, ohne Rücksicht auf Groß- und Kleinschreibung, im Betreff, im Absender (Adresse und Anzeigename), in den Empfängern, im Text einer empfangenen E-Mail (einschließlich der früheren Nachrichten, die sie zitiert), in den Anhangsnamen und im Text ihrer PDF-, Word- und Excel-Anhänge (sobald dieser Text gelesen wurde). Chinesischer, japanischer und koreanischer Text wird in Wörter zerlegt. Jedes Wort von query muss irgendwo in derselben E-Mail passen; from, to, cc und bcc nehmen Wörter einer Adresse oder eines Namens. Gesendete E-Mails werden nach Betreff, Absender und Empfängern durchsucht.

matched_email_id ist der beste Treffer des Threads, und highlights markiert die Wörter in seinem Betreff, Absender und seinen Empfängern (es ist {}, wenn nur der Text oder ein Anhangsname passte). Eine neue E-Mail ist ein bis zwei Sekunden nach dem Eintreffen durchsuchbar. Ist die Suche kurz nicht verfügbar, antwortet der Aufruf mit 503, search_unavailable und einem Retry-After-Header; jeder andere Aufruf funktioniert wie gewohnt.

Eine Thread-E-Mail hat direction, from, to, cc, bcc, reply_to, subject, message_id, html, text, attachments, read und received_at. Empfangene E-Mails ergänzen extracted_text (die Antwort, bereinigt um verborgenen Text), screening, spam_verdict und virus_verdict.

Aus einem Postfach senden

POST /inboxes/{id}/emails (inboxes.send() in den SDKs) beginnt mit einem Aufruf eine neue Unterhaltung von der Postfachadresse.

curl -X POST "https://api.billionsend.com/inboxes/{id}/emails" \
  -H "Authorization: Bearer bs_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1042-confirmation" \
  -d '{
    "to": "success@simulator.amazonses.com",
    "subject": "Your order 1042",
    "text": "It ships today. The invoice is attached.",
    "attachments": [{ "filename": "invoice.pdf", "content": "JVBERi0xLjQK..." }]
  }'

Der Aufruf nimmt to, subject, html und/oder text entgegen, optional cc, bcc, attachments und requires_approval. Die Regeln des Postfachs entscheiden wie bei einer Antwort, und die Antworten sind die einer Antwort: 200 mit { "id", "thread_id" } oder 202 mit dem Entwurf, wenn die Regeln den Versand zurückhalten (ein Postfach, das keine Unterhaltungen beginnen darf, ein erstmaliger Empfänger über den Anlauf hinaus, requires_approval: true). Ein auf ein Postfach beschränkter Schlüssel kann ihn für sein eigenes Postfach aufrufen.

Anhänge sind die, die POST /emails entgegennimmt: filename und base64-kodierter content, optional content_type und content_id für ein Inline-Bild. Ein entfernter path wird mit 422 beantwortet. Antworten, Weiterleitungen, neue Sendungen und Entwürfe nehmen sie alle entgegen, insgesamt bis 10 MiB dekodiert (eine Weiterleitung zählt auch die Dateien des Originals); Programme und getarnte Dateitypen werden mit 422 beantwortet, und ein Postfach auf der gemeinsamen Domain nimmt keine entgegen.

Antworten und weiterleiten

curl -X POST "https://api.billionsend.com/inboxes/{id}/threads/{thread_id}/emails/{email_id}/reply" \
  -H "Authorization: Bearer bs_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1042-reply" \
  -d '{ "text": "Thanks, your order ships today." }'

Eine Antwort geht an den Reply-To der Nachricht oder sonst an ihren Absender. reply_all fügt die anderen to- und cc-Adressen als cc hinzu; bcc wird nie kopiert. Eine Sendung nimmt höchstens 50 Empfänger auf. …/forward braucht to, nimmt eine Notiz entgegen und zitiert das Original mit seinen Anhängen, plus alle attachments, die Sie hinzufügen (insgesamt bis 10 MiB). Beide nehmen attachments und requires_approval: true entgegen, damit ein Mensch den Versand freigibt. Eine Antwort aus einem Agent-Postfach trägt Auto-Submitted: auto-replied.

Antwort Bedeutet
200 Gesendet: { "id", "thread_id" }.
202 Für einen Menschen zurückgehalten: der Entwurf, mit status: "pending_approval" und seinen approval_reasons.
403 inbox_send_policy Die Regeln des Postfachs lehnen den Versand rundweg ab.
403 email_quarantined Die E-Mail ist in Quarantäne oder trägt einen Virus.
403 restricted_api_key Ein auf ein Postfach beschränkter Schlüssel erreicht ein anderes Postfach.
429 inbox_send_cap_reached Das Tageslimit des Postfachs ist aufgebraucht; retry-after zählt bis Mitternacht UTC.

Um auf eine beliebige empfangene E-Mail zu antworten, ob in einem Postfach oder nicht, nutzen Sie POST /emails/receiving/{id}/reply.

Entwürfe und Freigabe

Ein Entwurf steht für sich allein bei einer neuen Unterhaltung oder ist eine Antwort mit thread_id und reply_to_email_id. Sein status:

status Bedeutet
draft Wird geschrieben; nichts sendet ihn, bis …/send aufgerufen wird oder sein send_at eintritt.
pending_approval Ein Versand wurde zurückgehalten und wartet auf einen Menschen. approval_reasons nennt den Grund. Er läuft nach 7 Tagen ab.
sent Gesendet; email_id nennt die E-Mail.
rejected Ein Mensch hat ihn abgelehnt.
expired Niemand hat ihn innerhalb von 7 Tagen freigegeben.
Aufruf Bewirkt
POST /inboxes/{id}/drafts Legt einen Entwurf an: to, cc, bcc, subject, text, html, attachments, plus thread_id und reply_to_email_id für eine Antwort. Ein Antwortentwurf kopiert keine Empfänger, setzen Sie also to vor dem Senden.
GET /inboxes/{id}/drafts Ungesendete Entwürfe, zuletzt aktualisierte zuerst.
GET / PATCH / DELETE /inboxes/{id}/drafts/{draft_id} Einen Entwurf lesen, ändern (das Setzen von text oder html ersetzt den ganzen Inhalt, und attachments ersetzt die ganze Liste) oder löschen; 409, sobald er gesendet ist.
POST /inboxes/{id}/drafts/{draft_id}/send Sendet ihn. 200 mit id und thread_id der gesendeten E-Mail, 202 wenn zurückgehalten, 422 ohne Empfänger.
POST /inboxes/{id}/drafts/{draft_id}/reject Lehnt einen Entwurf ab (nur Freigebende).

Ein Entwurf hält seine attachments verschlüsselt, getrennt von seinem Inhalt, und liest sie nach Position als id, filename, content_type und size zurück, nie den Inhalt. Sie gehen mit der E-Mail hinaus, wenn der Entwurf gesendet wird, und ein zurückgehaltener Versand behält die Dateien, die er trug, bei seinem Entwurf. Sobald ein Entwurf gesendet, abgelehnt, abgelaufen oder gelöscht ist, sind seine Dateien weg, und die Inhaltsbereinigung nach 30 Tagen entfernt alle übrigen.

Geplanter Versand. send_at bei POST oder PATCH (eine BillionSend-Erweiterung) sendet den Entwurf später, als wer es gesetzt hat (eine Änderung am Inhalt eines geplanten Entwurfs macht den Bearbeitenden zu dem, als den er sendet): eine ISO-8601-Zeit mit Offset oder eine relative wie "in 2 hours", höchstens 30 Tage im Voraus; eine bereits vergangene Zeit sendet ihn innerhalb einer Minute, und null bricht ab. Der Entwurf braucht bis dahin einen Empfänger, und nur ein draft kann geplant werden: Einer, der auf Freigabe wartet, antwortet mit 409. Wenn send_at eintritt, durchläuft der Versand jede Regel und jedes Limit wie ein Versand, der dann erfolgt. Gesendet, wird der Entwurf sent; von den Regeln des Postfachs zurückgehalten, pending_approval; abgelehnt (der Schlüssel, der ihn geplant hat, wurde widerrufen, das Postfach ist weg, ein Limit wurde erreicht), bleibt er ein draft, mit send_at wieder auf null, dem Namen der Ablehnung in send_error und einem Webhook inbox.draft.send_failed, der error: { name, message } trägt. Ihn erneut zu planen löscht send_error. Mit send_at antwortet das Anlegen eines zweiten Antwortentwurfs für dieselbe E-Mail mit 409, statt den vorhandenen Entwurf zu liefern.

Wer freigibt. Ein Mensch im Dashboard oder ein API-Schlüssel mit vollem Zugriff des Teams, der nicht auf ein Postfach beschränkt ist, gibt durch Senden frei: Der Versand überspringt die Regeln, die Agent-E-Mails zurückhalten. Ein Agent kann nicht freigeben: Ein auf ein Postfach beschränkter Schlüssel oder ein MCP-Client, der einen ausstehenden Entwurf sendet, erhält 403 approval_required. Im Dashboard kann jedes Mitglied Entwürfe unter dem Tab Zu prüfen des Postfachs freigeben, bearbeiten oder verwerfen, und Inhaber erhalten eine E-Mail pro Tag, solange etwas wartet.

Gründe, warum ein Versand zurückgehalten wird:

Grund Zurückgehalten, weil
approval_required Die Anfrage einen Menschen verlangt hat (requires_approval: true).
require_approval Das Postfach jeden Versand freigeben lässt.
send_policy Ein Empfänger von der Versandrichtlinie des Postfachs nicht erlaubt ist.
ramp Heute zu viele neue Empfänger für ein junges Postfach.
private_code Er einen Code oder Anmeldelink enthält, den das Postfach empfangen hat.
loop_guard:<reason> Er auf eine automatische Nachricht antwortet (Abwesenheitsnotiz, Mailingliste, Bounce).
loop_burst Zu viele automatische Antworten an eine Adresse innerhalb einer Stunde.
reply_to_redirect Der Reply-To der Nachricht auf eine andere Organisation zeigt.

Sicherheitseinstellungen

GET /inboxes/{id}/safety liest die Regeln eines Postfachs, und PATCH ändert jede davon:

curl -X PATCH "https://api.billionsend.com/inboxes/{id}/safety" \
  -H "Authorization: Bearer bs_..." \
  -H "Content-Type: application/json" \
  -d '{
    "accept_from": "allowlist",
    "allowlist": ["*@billing.example.net", "maria@example.org"]
  }'
Einstellung Bewirkt
accept_from Wessen E-Mails das Postfach erreichen: anyone; verified, Absender, deren Domain für die From-Adresse bürgt (plus Inhaber, die Allowlist und bekannte Threads); oder allowlist, nur Inhaber, die Allowlist und bekannte Threads. Der Rest kommt in Quarantäne.
allowlist Bis zu 500 Einträge: name@domain oder *@domain für eine Domain und ihre Subdomains.
owner_addresses Bis zu 50 weitere Adressen, die neben den Anmeldeadressen Ihrer Teammitglieder als Inhaber des Postfachs gelten. Auf der gemeinsamen Domain ignoriert.
screening E-Mails externer Absender auf Prompt-Injection und Phishing bewerten (Agent-Postfächer).
extract_codes Bestätigungscodes und Anmeldelinks aus E-Mails ziehen.
send_policy reply_only; allowlist, was neue Unterhaltungen mit Inhabern und der Allowlist hinzufügt (nicht auf der gemeinsamen Domain); oder open, jeder, sobald das Team seine ersten Sendungen hinter sich hat.
require_approval Jeder Versand aus dem Postfach wartet auf einen Menschen.
private_codes Ein Code oder Anmeldelink, den das Postfach empfangen hat, darf an niemanden außer Inhaber und die Allowlist gesendet werden.
send_cap Empfänger, an die das Postfach pro UTC-Tag ohne einen Menschen senden darf: 1 bis 100.000 oder null für kein Limit (1 bis 50 auf der gemeinsamen Domain).
forward_to Bis zu 5 Adressen, die eine Kopie jeder zugestellten Nachricht außer Spam erhalten: Anmeldeadressen von Teammitgliedern oder Inhaberadressen. Eine Kopie, die nicht sofort hinausgehen kann, wird wiederholt, bis sie gesendet, endgültig abgelehnt wurde oder zwei Tage vergangen sind; sie wird nie zweimal gesendet.

Eine Einstellung, die eine Regel verletzt, wird mit 422 und dem Grund beantwortet. Ein auf ein Postfach beschränkter Schlüssel kann diese Einstellungen nicht ändern (403 restricted_api_key), ein Agent-Schlüssel ebenso wenig. Ein MCP-Client kann sie lesen, aber nicht ändern. Nur ein Inhaber, Admin oder Entwickler ändert sie, im Dashboard oder mit einem API-Schlüssel mit vollem Zugriff. Agent-Sicherheit erklärt, was jede davon bewirkt.

Quarantäne

E-Mails, die die Regeln eines Postfachs nicht hereinlassen, kommen in Quarantäne: aufbewahrt, gelistet und freigebbar, nie verworfen und nie an ihren Absender zurückgeschickt. Sie lösen kein email.received oder inbox.email.received aus, bis sie freigegeben werden, und Agents sehen sie nie.

GET /inboxes/{id}/quarantine listet die zurückgehaltenen Nachrichten mit id, from, subject, quarantine_reason, sender_trust, injection_score, phishing_score und virus_signature, ohne Inhalt. POST /inboxes/{id}/quarantine/{email_id}/release stellt eine zu, und { "trust_sender": true } fügt ihren Absender außerdem der Allowlist hinzu. Beide brauchen einen Schlüssel mit vollem Zugriff, der nicht auf ein Postfach beschränkt ist. Menschen geben über den Tab Zu prüfen des Postfachs frei, und MCP-Clients mit receiving:manage nutzen release_email. Wer welche Zurückhaltung freigeben darf, steht in Agent-Sicherheit.

Bestätigungscodes

GET /inboxes/{id}/codes/latest antwortet mit dem neuesten Bestätigungscode oder Anmeldelink, den das Postfach empfangen hat, sodass ein Agent nie HTML liest:

curl "https://api.billionsend.com/inboxes/{id}/codes/latest?from=example.org&wait=30" \
  -H "Authorization: Bearer bs_..."
{
  "object": "verification_code",
  "status": "found",
  "kind": "link",
  "code": null,
  "url": "https://app.example.org/verify?token=Qm9vdHN0cmFwLTQ4MjkxMw",
  "link_domain_matches_sender": true,
  "email_id": "155252fb-e93e-45ee-8c19-5080a929c28b",
  "from": "no-reply@example.org",
  "received_at": "2026-10-12T14:03:11.229Z",
  "sender_trust": "external"
}
  • kind ist otp (Code in code) oder link (Adresse in url, mit link_domain_matches_sender).
  • from grenzt auf einen Absender ein; wait (0 bis 50 Sekunden) wartet, bis einer eintrifft; max_age (60 bis 86.400 Sekunden, standardmäßig 600) überspringt ältere Codes; since überspringt E-Mails, die zu oder vor dieser Zeit empfangen wurden. Übergeben Sie also das received_at eines bereits verwendeten Codes, um auf den nächsten zu warten.
  • status ist found, none, ambiguous (zwei Codes gleich wahrscheinlich, also wird keiner geliefert) oder timeout. Die Antwort ist immer 200.
  • Codes stammen nie aus E-Mails in Quarantäne, von Absendern, die die Authentifizierung nicht bestanden haben, oder aus einem Postfach mit ausgeschaltetem extract_codes. Jeder Lesezugriff wird in der Aktivität des Postfachs protokolliert.

Event-Stream

GET /inboxes/events ist ein Server-Sent-Event-Stream von allem, was in Ihren Postfächern geschieht, im Moment des Commits. Events tragen die Namen der Webhook-Events (inbox.email.received, inbox.thread.created, inbox.draft.created, email.received und die anderen inbox.*-Events) und das data der Webhook-Nutzdaten. GET /inboxes/{id}/events streamt ein Postfach und endet, wenn dieses Postfach gelöscht wird oder abläuft.

curl -N "https://api.billionsend.com/inboxes/events?types=inbox.email.received" \
  -H "Authorization: Bearer bs_..." \
  -H "Accept: text/event-stream"
retry: 1000

id: 812.40.1790000000
event: inbox.email.received
data: {"type":"inbox.email.received","created_at":"2026-11-15T09:20:30.131Z","inbox_id":"7eeb9517-aed7-40d7-ad65-500be42ed147","data":{"source":"system","inbox_id":"7eeb9517-aed7-40d7-ad65-500be42ed147","thread_id":"...","email_id":"...","email":{}}}

: keepalive
  • Senden Sie den Schlüssel als Bearer-Header, wie bei jeder Anfrage. Das EventSource von Browsern kann ihn nicht setzen: Nutzen Sie fetch und lesen Sie den Body, oder einen beliebigen SSE-Client, der Header akzeptiert.
  • types grenzt den Stream auf einige Events ein, durch Kommas getrennt; /inboxes/{id}/events sendet weiterhin inbox.deleted und inbox.expired, die Events, die ihn beenden. Jedes Event enthält nur Metadaten, wie ein Webhook: keinen Inhalt, Code oder Link. Lesen Sie die Nachricht mit den Empfangs-Endpunkten.
  • Fortsetzen. Jedes Event hat eine id. Ein Client, der sich mit Last-Event-ID (oder ?last_event_id=) neu verbindet, erhält, was er verpasst hat, der Reihe nach, vor den Live-Events. Events werden 24 Stunden aufbewahrt; eine Neuverbindung mit einer älteren ID erhält zuerst ein Event stream.gap, das bedeutet, dass Events fehlen können und die Listen erneut gelesen werden sollten.
  • Ein Stream beginnt ohne Wiedergabe, wenn er keine Last-Event-ID hat. Der Server schließt ihn etwa alle 10 Minuten und wenn die API neu startet: Verbinden Sie sich mit der zuletzt gesehenen id neu. retry: 1000 bittet einen Client, eine Sekunde zu warten. Eine Kommentarzeile alle 15 Sekunden verhindert, dass Proxys einen ruhenden Stream schließen.
  • Ein teamweiter Schlüssel öffnet /inboxes/events. Ein auf eine Domain oder ein Postfach beschränkter Schlüssel öffnet /inboxes/{id}/events für ein Postfach, das er erreichen kann. Ein Schlüssel nur zum Senden kann keinen Stream öffnen.
  • Ein Agent (ein auf ein Postfach beschränkter Schlüssel oder eine MCP-Verbindung) erhält inbox.email.quarantined nie, weder live noch wiedergegeben, da er zurückgehaltene E-Mails nie liest; es in types zu nennen ist ein 403 restricted_api_key.
  • Ein Stream schließt innerhalb weniger Sekunden, sobald sein Schlüssel widerrufen wird, die Person, die den Schlüssel erstellt hat, das Team verlässt oder sein Postfach gelöscht wird oder abläuft.
  • Jeder Schlüssel darf auf jedem API-Prozess 5 Streams gleichzeitig halten und jedes Team 25; ein weiterer wird mit 429 too_many_streams und retry-after beantwortet. Ein Stream für das ganze Team genügt den meisten Agents.

wait bei /emails/receiving und codes/latest wird von denselben Events geweckt, das Warten kostet also nichts, solange keine E-Mails eintreffen.

Auf ein Postfach beschränkte API-Schlüssel

Geben Sie jedem Agent einen Schlüssel, der nur sein eigenes Postfach erreicht. Siehe API-Schlüssel.

curl -X POST "https://api.billionsend.com/api-keys" \
  -H "Authorization: Bearer bs_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "orders agent",
    "permission": "full_access",
    "inbox_id": "7eeb9517-aed7-40d7-ad65-500be42ed147"
  }'
  • Er braucht permission: "full_access" und kann nicht zusätzlich eine domain_id nehmen. Ein Postfach hält höchstens 5 aktive Schlüssel, außerhalb des Teamlimits von 25.
  • Der Schlüssel liest sein Postfach (Threads, E-Mails, Entwürfe, Labels, Codes, den Event-Stream und /emails/receiving auf dieses Postfach beschränkt), antwortet, leitet weiter, schreibt Entwürfe und sendet sie, sendet neue E-Mails aus seinem Postfach und sendet nur von der Adresse des Postfachs (403 restricted_api_key bei einem anderen from; 550 5.7.1 über SMTP).
  • Alles andere wird mit 403 restricted_api_key beantwortet: Er kann keine Sicherheitseinstellungen ändern, keine Quarantäne listen oder freigeben, keine Entwürfe freigeben, keine Schlüssel erstellen und kein anderes Postfach erreichen.
  • Er funktioniert nicht mehr, wenn sein Postfach abläuft, und das Löschen des Postfachs widerruft ihn.

Im Dashboard wählen Inhaber, Admins und Entwickler das Postfach beim Erstellen eines Schlüssels unter Auf ein Postfach beschränken.

Webhooks

Postfach-Events (inbox.created, inbox.thread.created, inbox.email.received, inbox.email.sent, inbox.email.quarantined, inbox.expired, die inbox.draft.*-Events und mehr) gehen nur an Endpunkte, die sie nennen, nie an einen Endpunkt, der alle Events abonniert hat. Ein Endpunkt lässt sich mit inbox_ids auf einige Postfächer beschränken. email.received wird für Postfach-E-Mails weiterhin ausgelöst, sobald sie zugestellt sind. Nutzdaten: Webhooks.

Aktivität

Alles, was in einem Postfach getan wird, wird protokolliert: Sendungen und die Entscheidungen der Regeln, Ablehnungen, Entwürfe, Freigaben, Freigaben aus der Quarantäne, Code-Lesezugriffe, Sicherheitsänderungen, Löschungen und Schlüssel. Der Tab Aktivität des Postfachs listet es auf, mit dem, der gehandelt hat: ein Mensch, ein API-Schlüssel oder eine verbundene App. Entscheidungen behalten nur Grundcodes, nie Inhalte, Codes oder Adressen.

Limits

Limit Wert
Postfächer 3 bei Free, 25 bei Starter, unbegrenzt bei Pro und Scale.
Pro Stunde angelegte Postfächer 10 bei Free, 60 bei Starter, 600 bei Pro und Scale.
E-Mails pro Postfach 200 angenommene Nachrichten pro gleitender Stunde bei einem Agent-Postfach, 2.000 bei einem Postfach für Menschen. Darüber erhalten Absender 452 4.2.2 und versuchen es später erneut.
Versand send_cap Empfänger pro UTC-Tag. Ein neues Postfach erreicht neue Empfänger schrittweise: 10 an seinem ersten Versandtag, dann 20, 40, 80, 160 und so weiter, bis zum Limit.
Empfänger pro Sendung 50 (to, cc und bcc zusammen); 10 von einer gemeinsamen Adresse.
Anhänge pro Sendung 10 MiB dekodiert insgesamt; keine von einer gemeinsamen Adresse.
Gemeinsame Domain 1.000 Empfänger pro UTC-Tag für alle gemeinsamen Adressen Ihres Teams; ein 90 Tage lang ungenutztes gemeinsames Postfach wird gelöscht.
Labels 100 pro Postfach.
Sicherheitslisten 500 Allowlist-Einträge, 50 Inhaberadressen, 5 forward_to-Adressen.
Auf ein Postfach beschränkte Schlüssel 5 aktive pro Postfach.
Prüfung 200 Nachrichten pro Postfach und Tag; darüber kommen E-Mails, die geprüft werden müssen, in Quarantäne.
Warten 50 Sekunden pro Anfrage; 20 Wartevorgänge gleichzeitig pro Team auf jedem API-Prozess.
Event-Streams 5 pro API-Schlüssel und 25 pro Team gleichzeitig auf jedem API-Prozess; Events werden 24 Stunden lang wiedergegeben.
Entwürfe und Papierkorb Ein ausstehender Entwurf läuft nach 7 Tagen ab; ein Thread im Papierkorb wird nach 30 gelöscht.
Aufbewahrung Postfach-E-Mails folgen der Aufbewahrung empfangener E-Mails: 30 Tage.

Postfächer selbst kosten nichts: Empfangene E-Mails zählen einmal pro Nachricht auf Ihr Empfangslimit, nie auf Ihr Sendevolumen, wie unter Empfang.

Dashboard

Postfächer in der Seitenleiste listet Ihre Postfächer unter den Tabs Alle, Agent und Personen auf, mit dem, was Aufmerksamkeit braucht: Entwürfe zur Freigabe, ungelesene Threads und E-Mails in Quarantäne. Eine angeheftete Zeile Alle empfangenen öffnet jede E-Mail, die Ihre Domains empfangen haben. Die Seite eines Postfachs hat vier Tabs: Threads (lesen, antworten und Entwürfe direkt freigeben), Zu prüfen (Entwürfe und Quarantäne), Sicherheit & Regeln und Aktivität.

Jedes Mitglied kann die Threads eines Postfachs bearbeiten, Entwürfe freigeben und Quarantäne aufheben. Inhaber, Admins und Entwickler können zusätzlich Postfächer anlegen, ändern und löschen, Sicherheitsregeln ändern, auf ein Postfach beschränkte Schlüssel erstellen, empfangene E-Mails löschen und Catch-all umschalten. Siehe Teamrollen.

MCP

MCP-Clients arbeiten mit Postfächern unter drei Berechtigungen: receiving:read (E-Mails lesen, auf sie warten, Codes lesen, Postfächer, Threads, Labels und Entwürfe listen, Threads durchsuchen, Sicherheitsregeln lesen), receiving:reply (antworten, weiterleiten, aus einem Postfach senden, Entwürfe schreiben, senden und löschen, Threads und Labels ordnen) und receiving:manage (Postfächer anlegen, ändern und löschen, Quarantäne listen und freigeben). Ein MCP-Client sieht E-Mails immer so, wie es ein Agent tut: ohne zurückgehaltene E-Mails und mit als nicht vertrauenswürdig eingegrenztem Nachrichtentext. Er gibt nie Entwürfe frei, und create_inbox nimmt accept_from und keine andere Sicherheitseinstellung entgegen; er ändert nie die Sicherheitsregeln eines Postfachs.

API-Hinweise

  • Das Anlegen eines Postfachs oder Entwurfs antwortet mit dem ganzen Objekt.
  • email_address ist optional: Wird sie weggelassen, erhält das Postfach eine zufällige dauerhafte Adresse auf der gemeinsamen Domain.
  • kind ist standardmäßig agent, ein ohne ihn angelegtes Postfach erhält also die Schutzmaßnahmen eines Agents.
  • Es gibt keinen gehosteten Agent: GET /inboxes/{id}/agent antwortet mit leeren instructions, tone und actions, und PATCH /inboxes/{id}/agent antwortet mit 422.
  • Nicht unterstützt: eigene headers bei Antworten, Weiterleitungen und Entwurfssendungen sowie path-Anhänge (Remote-URL). Jedes wird mit 422 beantwortet, sofern sein Wert nicht leer ist.
  • Eine Antwort, Weiterleitung oder Entwurfssendung, die die Regeln des Postfachs zurückhalten, antwortet mit 202 und dem Entwurf statt mit 200 und der E-Mail: Prüfen Sie, ob object inbox_draft lautet, bevor Sie das Ergebnis als gesendet behandeln.
  • Postfach-Fehler: 403 inbox_send_policy, 429 inbox_send_cap_reached, 403 approval_required, 403 email_quarantined und 503 name_review_unavailable (siehe Fehler).
  • inbox.*-Webhook-Events sind Opt-in; inbox.thread.assigned und inbox.thread.unassigned werden nicht gesendet.

War diese Seite hilfreich?