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) |
agentist der Standard, wennkindfehlt. 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.humanist für Menschen, die im Dashboard lesen: Die E-Mails aller werden zugestellt (eine fehlgeschlagene Authentifizierung landet im Ordnerspam), 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 /inboxeslistet Postfächer, neueste zuerst (?kind=agentoder?kind=humangrenzt 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}ändertname,from_nameoderexpires_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:
- an das Postfach mit genau dieser Adresse;
- sonst bei
name+tag@an das Postfach vonname@; - 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_innichts 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_policyopenist 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 mit403 inbox_send_policybeantwortet. - Jede E-Mail geht an höchstens 10 Empfänger. Ein Postfach sendet an höchstens 50 Empfänger pro Tag (
send_capvon 1 bis 50), und alle gemeinsamen Adressen Ihres Teams zusammen erreichen 1.000 Empfänger pro UTC-Tag; darüber429 inbox_send_cap_reached. frommuss genau die Adresse des Postfachs sein, und die E-Mail darf wederscheduled_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_tonimmt 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 ihrIn-Reply-Toeine 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,sentodertrash. Neue E-Mails holen einen archivierten oder gesendeten Thread zurück nachinbox.DELETEverschiebt einen Thread nachtrash, der nach 30 Tagen geleert wird. - Lesestatus. Ein
PATCHmitreadmarkiert 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"
}
kindistotp(Code incode) oderlink(Adresse inurl, mitlink_domain_matches_sender).fromgrenzt 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 dasreceived_ateines bereits verwendeten Codes, um auf den nächsten zu warten.statusistfound,none,ambiguous(zwei Codes gleich wahrscheinlich, also wird keiner geliefert) odertimeout. Die Antwort ist immer200.- 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. DasEventSourcevon Browsern kann ihn nicht setzen: Nutzen Siefetchund lesen Sie den Body, oder einen beliebigen SSE-Client, der Header akzeptiert. typesgrenzt den Stream auf einige Events ein, durch Kommas getrennt;/inboxes/{id}/eventssendet weiterhininbox.deletedundinbox.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 mitLast-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 Eventstream.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-IDhat. Der Server schließt ihn etwa alle 10 Minuten und wenn die API neu startet: Verbinden Sie sich mit der zuletzt gesehenenidneu.retry: 1000bittet 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}/eventsfü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.quarantinednie, weder live noch wiedergegeben, da er zurückgehaltene E-Mails nie liest; es intypeszu nennen ist ein403 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_streamsundretry-afterbeantwortet. 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 einedomain_idnehmen. 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/receivingauf 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_keybei einem anderenfrom;550 5.7.1über SMTP). - Alles andere wird mit
403 restricted_api_keybeantwortet: 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_addressist optional: Wird sie weggelassen, erhält das Postfach eine zufällige dauerhafte Adresse auf der gemeinsamen Domain.kindist standardmäßigagent, ein ohne ihn angelegtes Postfach erhält also die Schutzmaßnahmen eines Agents.- Es gibt keinen gehosteten Agent:
GET /inboxes/{id}/agentantwortet mit leereninstructions,toneundactions, undPATCH /inboxes/{id}/agentantwortet mit422. - Nicht unterstützt: eigene
headersbei Antworten, Weiterleitungen und Entwurfssendungen sowiepath-Anhänge (Remote-URL). Jedes wird mit422beantwortet, sofern sein Wert nicht leer ist. - Eine Antwort, Weiterleitung oder Entwurfssendung, die die Regeln des Postfachs zurückhalten, antwortet mit
202und dem Entwurf statt mit200und der E-Mail: Prüfen Sie, obobjectinbox_draftlautet, bevor Sie das Ergebnis als gesendet behandeln. - Postfach-Fehler:
403 inbox_send_policy,429 inbox_send_cap_reached,403 approval_required,403 email_quarantinedund503 name_review_unavailable(siehe Fehler). inbox.*-Webhook-Events sind Opt-in;inbox.thread.assignedundinbox.thread.unassignedwerden nicht gesendet.