---
title: Postfächer
description: E-Mail-Adressen, die E-Mails in Threads ordnen und von derselben Adresse antworten, für einen KI-Agent oder für Menschen.
seo:
  title: E-Mail-Postfächer für KI-Agents
ai:
  exclude: true
---

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](/docs/de/mcp) liest, oder Menschen, die es im Dashboard lesen. Ein Postfach ist eine Adresse auf einer Ihrer [empfangenden Domains](/docs/de/receiving) oder eine Adresse auf der gemeinsamen Domain von BillionSend, die kein DNS braucht.

Die [SDKs](/docs/de/sdks) decken jeden Postfach-Endpunkt als `inboxes.*` ab, einschließlich der Sicherheitsregeln, der Quarantäne, der Freigaben und des Live-Event-Streams.

> **Info**
>
> Postfächer sind in der Beta, im Dashboard unter **Postfächer**.

## 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](/docs/de/agent-safety).
- **`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:

```sh
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:

```ts
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](/docs/de/receiving): 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:

```sh
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.

```sh
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

```sh
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`](/docs/de/receiving).

## 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:

```sh
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](/docs/de/agent-safety) 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](/docs/de/agent-safety).

## 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:

```sh
curl "https://api.billionsend.com/inboxes/{id}/codes/latest?from=example.org&wait=30" \
  -H "Authorization: Bearer bs_..."
```

```json
{
  "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.

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

```text
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](/docs/de/receiving)-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](/docs/de/api-keys).

```sh
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](/docs/de/concepts/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](/docs/de/receiving).

## 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](/docs/de/team-roles).

## MCP

[MCP-Clients](/docs/de/mcp) 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](/docs/de/api-reference/basics)).
- `inbox.*`-Webhook-Events sind Opt-in; `inbox.thread.assigned` und `inbox.thread.unassigned` werden nicht gesendet.
