---
title: Empfang
description: E-Mails auf Ihrer eigenen Domain empfangen und über die API, Webhooks und das Dashboard lesen.
seo:
  title: Inbound-E-Mail-API
ai:
  exclude: true
---

Der Empfang macht aus einer von Ihnen verifizierten Domain einen Ort, der E-Mails annimmt. Eingehende Nachrichten werden verschlüsselt gespeichert und erreichen Sie über die API, den `email.received`-Webhook, das Dashboard (**Postfächer → Alle empfangenen**) und den [MCP-Server](/docs/de/mcp).

Es gibt zwei Wege, festzulegen, welche Adressen E-Mails annehmen: Legen Sie für eine Adresse ein [Postfach](/docs/de/inboxes) an, oder schalten Sie **Catch-all** ein, um jede andere Adresse der Domain anzunehmen.

> **Info**
>
> Der Empfang ist in der öffentlichen Beta. Jede Nachricht erhält einen Spam-Score, eine Vertrauensstufe des Absenders und eine Virenprüfung. Infizierte E-Mails werden zurückgehalten; alles andere wird mit diesen Ergebnissen gespeichert, damit Ihr Code darauf reagieren kann.

## Einrichten

1. **Wählen Sie einen Namen, der noch keine E-Mails empfängt**, zum Beispiel `inbound.example.com`. Der MX-Eintrag übernimmt jede Adresse auf dem Namen, auf dem er veröffentlicht ist, Ihre Postfächer bei `example.com` bleiben also bei Ihrem jetzigen Anbieter.
2. **Fügen Sie genau diesen Namen unter **Domains** hinzu und verifizieren Sie ihn**, wie beim [Senden](/docs/de/concepts/domains). Die Verifizierung von `example.com` deckt dessen Subdomains nicht ab.
3. **Schalten Sie den Empfang ein**: Öffnen Sie die Domain und aktivieren Sie **Empfang aktivieren**, oder rufen Sie die API auf:

   ```sh
   curl -X PATCH "https://api.billionsend.com/domains/{id}" \
     -H "Authorization: Bearer bs_..." \
     -H "Content-Type: application/json" \
     -d '{ "capabilities": { "receiving": "enabled" } }'
   ```

   Ein Name kann nur in einem Team empfangen; ein Name, auf dem bereits ein anderes Team empfängt, wird mit `409` beantwortet.
4. **Veröffentlichen Sie beide MX-Einträge**, die bei den Einträgen der Domain stehen, bei Ihrem DNS-Anbieter:

   | Typ | Name | Wert | Priorität |
   | --- | --- | --- | --- |
   | MX | `inbound.example.com` | `mx1.billionsend-dns.com` | `10` |
   | MX | `inbound.example.com` | `mx2.billionsend-dns.com` | `10` |

   Jeder ist ein eigener Mailserver. Sind beide veröffentlicht, versucht es ein Absender, der einen davon nicht erreicht, innerhalb von Sekunden beim anderen. Veröffentlichen Sie daher beide mit gleicher Priorität. Jede Zeile gilt als verifiziert, sobald auf diesem Namen kein anderer MX-Eintrag eine niedrigere Prioritätszahl hat.
5. **Wählen Sie die Adressen**: [Legen Sie für jede Adresse ein Postfach an](/docs/de/inboxes) oder schalten Sie auf der Domainseite **Catch-all** ein. Ohne beides lehnt die Domain alle E-Mails ab.
6. **Senden Sie eine Testnachricht** von einem beliebigen Postfach. Sie erscheint innerhalb von Sekunden unter **Postfächer → Alle empfangenen**.

Um den Empfang zu beenden, schalten Sie ihn aus (`"receiving": "disabled"`) und entfernen Sie den MX-Eintrag. Bereits gespeicherte E-Mails bleiben, bis die Aufbewahrungsfrist sie entfernt.

## Welche Adressen empfangen

- Die Adresse jedes [Postfachs](/docs/de/inboxes) auf der Domain und ihre `+tag`-Varianten: `orders+4821@` erreicht das Postfach von `orders@`.
- Bei eingeschaltetem **Catch-all** auch jede andere Adresse: `support@`, `invoices@`, `reply+ticket-4821@`. Lesen Sie `received_for` in Ihrem Code, um zu sehen, an welche Adresse eine Nachricht ging.

Bei ausgeschaltetem Catch-all wird jede andere Adresse abgelehnt, solange der Server des Absenders noch verbunden ist (`550 5.1.1`). Der Absender erhält also einen Bounce von seinem eigenen Server, und nichts wird gespeichert.

Catch-all ist standardmäßig aus und erfordert einen kostenpflichtigen Tarif (Free antwortet mit `403 plan_limit_reached`). Inhaber, Admins und Entwickler schalten es auf der Domainseite ein oder mit `PATCH /domains/{id}` und `{ "receiving_catch_all": true }`.

- `received_for` listet die Adressen Ihrer Domains auf, an die die Nachricht tatsächlich zugestellt wurde, Bcc eingeschlossen. `to` und `cc` sind nur das, was die Header behaupten, richten Sie das Routing also nach `received_for`.
- Eine Nachricht wird einmal pro Team gespeichert, an wie viele Ihrer Adressen sie auch gesendet wurde.
- Nur der exakte Name empfängt: E-Mails an `x@eu.inbound.example.com` werden abgelehnt, sofern diese Subdomain nicht ebenfalls empfängt.

## Filterung und Limits

Unter **Einstellungen → Empfang** gibt es drei Schalter. Sie gelten für jede Domain Ihres Teams und wirken ab der nächsten Nachricht.

| Schalter | An | Aus |
| --- | --- | --- |
| Spam ab Score 5 ablehnen (standardmäßig an) | E-Mails mit einem Spam-Score ab 5 (auf einer Skala von 0 bis 10) werden mit `554 5.7.1` abgelehnt; nichts wird gespeichert. | Spam wird gespeichert: im Ordner `spam` eines Postfachs, bei einer Catch-all-Adresse nur markiert. |
| Anhänge über 10 MB entfernen (standardmäßig aus) | Jeder größere Anhang wird durch einen kurzen Hinweis `<file>.removed.txt` ersetzt, der sagt, was entfernt wurde. | Anhänge werden unverändert gespeichert. |
| Roh-.eml 30 Tage aufbewahren (standardmäßig an) | Der Inhalt bleibt für Ihre Aufbewahrungsfrist erhalten. | Der Inhalt (Text, HTML, Header, Rohnachricht, Anhänge) wird nach 1 Tag gelöscht. Metadaten und Webhooks bleiben unberührt. |

| Limit | Free | Starter, Pro, Scale |
| --- | --- | --- |
| Nachrichtengröße | 10 MB | 40 MB |
| Catch-all | Nein | Ja |
| Empfangene E-Mails | 100 pro UTC-Tag | Das Zweifache des Monatsvolumens Ihres Tarifs, jeden Monat |
| Darüber hinaus | Zurückgestellt bis Mitternacht UTC | Zurückgestellt, bis sich Ihr Volumen erneuert |
| Aufbewahrung | 30 Tage | 30 Tage |

- Die Größe zählt die gesamte gespeicherte Nachricht nach dem Entfernen von Anhängen. Base64 macht Anhänge etwa ein Drittel größer, bei 40 MB passen also rund 30 MB an Dateien hinein. Eine größere Nachricht wird mit `552 5.3.4` abgelehnt.
- Empfangene E-Mails zählen einmal pro Nachricht und Team auf ihr eigenes Limit. Sie verbrauchen nie Ihr Sendevolumen, und der Versand verbraucht nie Ihr Empfangslimit.
- Ist das Limit erreicht, wird der Server des Absenders angewiesen, es später erneut zu versuchen (`452 4.2.2`), und versucht es mehrere Tage lang weiter, meist bis zu fünf, sodass die Nachricht ankommt, sobald wieder Platz ist. E-Mails, die noch zurückgestellt sind, wenn der Server des Absenders aufgibt, gehen an den Absender zurück.
- Mit dem Ende der Aufbewahrung lesen sich `html`, `text`, `headers` und `raw` als `null`, `attachments` ist leer und Download-Links funktionieren nicht mehr. Absender, Empfänger und Betreff bleiben erhalten.

**Einstellungen → Abrechnung und Nutzung** zeigt empfangene E-Mails und ihr Limit. Postfächer selbst sind kostenlos.

## Empfangene E-Mails lesen

Nutzen Sie `emails.receiving` in den [SDKs](/docs/de/sdks) oder einfaches HTTP. Diese Endpunkte brauchen einen [API-Schlüssel](/docs/de/api-keys) mit **vollem Zugriff**; ein Schlüssel nur zum Senden erhält `403 restricted_api_key`. Ein auf eine Domain beschränkter Schlüssel liest nur die E-Mails dieser Domain, ein auf ein Postfach beschränkter nur die E-Mails dieses Postfachs.

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

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

const page = await bs.emails.receiving.list({ limit: 20 });
if (page.error) throw page.error;

const first = page.data.data[0];
const email = await bs.emails.receiving.get(first.id);
const files = await bs.emails.receiving.attachments.list(first.id);
```

| Aufruf | Liefert |
| --- | --- |
| `GET /emails/receiving` | Empfangene E-Mails, neueste zuerst, mit [der Paginierung, die jede Liste nutzt](/docs/de/api-reference/basics). |
| `GET /emails/receiving/{id}` | Eine E-Mail mit Inhalt, Authentifizierungsergebnissen und einem Download-Link für die Originalnachricht. |
| `GET /emails/receiving/{id}/attachments` | Ihre Anhänge, jeweils mit einem Download-Link. |
| `GET /emails/receiving/{id}/attachments/{attachment_id}/text` | Der Text eines PDF-, Word- oder Excel-Anhangs (BillionSend-Erweiterung). |
| `DELETE /emails/receiving/{id}` | Löscht die E-Mail sofort, mit ihren Anhängen und ihrem Platz in Postfächern. Erfordert einen Schlüssel mit vollem Zugriff, der nicht auf ein Postfach beschränkt ist, und im Dashboard die Rolle Inhaber, Admin oder Entwickler (**Jetzt löschen**). |

Die Liste nimmt `limit` (1 bis 100, Standard 20), `inbox_id`, `to`, `from` (eine Adresse oder eine Domain mit ihren Subdomains), `subject_contains`, `since`, `unread` und `wait` entgegen. Zurückgehaltene E-Mails bleiben außen vor, außer Sie übergeben `include_quarantined=true` oder `quarantined=true` (ein Schlüssel mit vollem Zugriff, der nicht auf ein Postfach beschränkt ist).

Jede E-Mail trägt außerdem `inbox_id`, `thread_id`, `screening`, `spam_verdict`, `virus_verdict` und `extracted`.

### Auf neue E-Mails warten

`wait` (1 bis 50 Sekunden) hält die Anfrage, bis passende E-Mails eintreffen, und antwortet dann sofort; bei Ablauf der Frist antwortet es mit einer leeren Liste. Es lässt sich mit den anderen Filtern kombinieren, ein Agent kann also auf die nächste Nachricht eines Absenders an ein Postfach warten:

```sh
curl "https://api.billionsend.com/emails/receiving?inbox_id=7eeb9517-aed7-40d7-ad65-500be42ed147&from=example.org&wait=30" \
  -H "Authorization: Bearer bs_..."
```

- Ohne `before` oder `since` zählen E-Mails der letzten 60 Sekunden, damit eine Nachricht, die kurz vor dem Aufruf eintraf, nicht verpasst wird.
- Die Antwort ergänzt `held`: passende Nachrichten, die seitdem zurückgehalten wurden, mit ihrer ID und ihrem Grund, damit ein Agent weiß, dass er nicht länger warten und einen Menschen informieren soll.
- Ein Team hält auf jedem API-Prozess 20 Wartevorgänge gleichzeitig; ein weiterer wird mit `429 too_many_waits` beantwortet.
- Ein Wartevorgang schaut in die Datenbank, wenn E-Mails eintreffen (dieselben Events wie beim [Event-Stream eines Postfachs](/docs/de/inboxes)), nicht nach einem Timer.

### Authentifizierungsergebnisse

`authentication` meldet SPF, DKIM und DMARC als `pass`, `fail`, `gray` (kein Urteil: kein Eintrag oder keine Signatur, oder ein neutrales Ergebnis), `processing_failed` (die Prüfung konnte nicht abgeschlossen werden) oder `unknown`. `dmarc: "pass"` bedeutet, dass die Domain in `from` die Nachricht autorisiert hat; alles andere bedeutet, dass `from` gefälscht sein kann. Die [Vertrauensstufe des Absenders](/docs/de/agent-safety) wird aus diesen Ergebnissen gebildet.

### Spam, Viren und Vertrauen

- `spam_verdict`: `pass`, `gray` (`spam_score` 25 bis 49) oder `fail` (50 oder mehr), aus einem Score von 0 bis 100, der sich aus Authentifizierung, Headern, Links, Anhängen und dem Score des Spamfilters auf den empfangenden Servern zusammensetzt (das Dashboard zeigt ihn auf einer Skala von 0 bis 10).
- `virus_verdict`: `pass`, `fail` (mit `virus_signature`), `processing_failed` (der Scanner konnte nicht antworten, die Nachricht wird also ungescannt zugestellt und dort, wo sie nicht geprüft wird, als verdächtig markiert) oder `null`, wenn kein Scan lief. Infizierte E-Mails werden zurückgehalten: Sie lösen kein `email.received` aus, bis ein Mensch sie im Dashboard freigibt, und ihre Downloads antworten mit `410 email_blocked`, auch nach einer Freigabe.
- `screening.sender_trust`: wie weit der Absender belegt ist. Siehe [Agent-Sicherheit](/docs/de/agent-safety).

### Inhalt

- `html_format`: `data_uri` (Standard) fügt Inline-Bilder ins HTML ein; `?html_format=cid` behält `cid:`-Verweise, die Sie mit der `content_id` jedes Anhangs abgleichen.
- `text` kommt ohne unsichtbare Zeichen; `html` ist exakt wie empfangen.
- `extracted_text` ist der Antwortteil der Nachricht, bereinigt um Text, den ein Mensch nicht sehen kann. `extracted` trägt einen Bestätigungscode (`code`) oder Anmeldelink (`link`), wenn die Nachricht einen enthält.

### Anhangstext

PDF-, Word- (`.docx`) und Excel-Anhänge (`.xlsx`) werden kurz nach Eintreffen der E-Mail einmal in einfachen Text gelesen und für Ihre Aufbewahrungsfrist bei der E-Mail gehalten. Die Zustellung wartet nie darauf. `GET /emails/receiving/{id}/attachments/{attachment_id}/text` (MCP `get_received_email_attachment_text`) antwortet mit:

- `status`: `pending`, bis die Datei gelesen wurde; `ok` mit `text`; `unsupported` für andere Dateien (ältere `.doc` und `.xls`, PowerPoint, Bilder); `encrypted` für eine passwortgeschützte Datei; `too_large` über 25 MB oder wenn das Lesen mehr Speicher bräuchte als erlaubt; `unreadable` für eine beschädigte Datei; `timeout` oder `failed`, wenn das Lesen nicht abgeschlossen wurde. `null` für E-Mails, die empfangen wurden, bevor Anhangstext gelesen wurde.
- `flags`: `truncated`, wenn ein Limit den Text gekürzt hat (100.000 Zeichen, die ersten 500 PDF-Seiten), `hidden_text`, wenn Text ausgelassen wurde, den ein Mensch beim Öffnen der Datei nicht sähe: versteckter Word-Text, versteckte Blätter, Zeilen und Spalten, unsichtbare Zeichen.
- `pages`: die Seitenzahl eines PDFs.
- `text`: Absätze und Tabellenzeilen auf eigenen Zeilen, Zellen und Spalten durch Tabulatoren getrennt, eine Überschrift `## Sheet name` pro Arbeitsblatt, Datumsangaben als ISO-Datum. Es wird nur die Textebene eines PDFs gelesen, ein Scan ohne Textebene liest sich also als leer. Formeln liefern ihre gespeicherten Werte.

Der Text stammt von einem externen Absender: Behandeln Sie ihn als Daten, nie als Anweisungen. Eine E-Mail mit Schadsoftware antwortet mit `410 email_blocked`.

### Downloads

`raw.download_url` und die `download_url` jedes Anhangs funktionieren ohne API-Schlüssel: Der Link selbst ist die Zugangsberechtigung. Ein Link ist für eine E-Mail signiert, funktioniert eine Stunde nach der Antwort der API nicht mehr, und jeder, der ihn besitzt, kann bis dahin herunterladen, protokollieren Sie ihn also nicht. Jeder Aufruf signiert neue Links. Downloads werden immer als Dateien ausgeliefert, nie im Browser dargestellt.

## Antworten und weiterleiten

`POST /emails/receiving/{id}/reply` und `…/forward` (`emails.receiving.reply()` und `forward()` in den SDKs) beantworten oder leiten eine Nachricht in einer Anfrage weiter, wobei die Threading-Header für Sie gesetzt werden:

```sh
curl -X POST "https://api.billionsend.com/emails/receiving/{id}/reply" \
  -H "Authorization: Bearer bs_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1042-reply" \
  -d '{ "text": "Thanks, we are on it." }'
```

- **Antworten** nimmt `text` oder `html`, `subject`, `cc`, `bcc` und `reply_all` entgegen. Die Antwort geht an den `Reply-To` der Nachricht oder sonst an ihren Absender.
- **Weiterleiten** nimmt `to`, `cc`, `bcc`, eine Notiz, `subject` und `mode` entgegen: `inline` (Standard) zitiert das Original, `attachment` hängt es als `forwarded_message.eml` an.
- `from` ist jede Adresse auf einer verifizierten Domain Ihres Teams; standardmäßig die Adresse des Postfachs, das die Nachricht erreicht hat. `requires_approval: true` hält den Versand für einen Menschen zurück.
- Beides zählt als gewöhnlicher Versand, mit bis zu 10 MiB Anhängen.

Sie antworten mit `200` und der `id` und `thread_id` der gesendeten E-Mail, oder mit `202` und einem Entwurf, wenn die Regeln eines Postfachs den Versand zurückhalten. Weitere Antworten: `403` (zurückgehaltene oder infizierte E-Mails, die Regeln eines Postfachs, ein auf ein Postfach beschränkter Schlüssel außerhalb seines Postfachs), `404`, `409` (wiederverwendeter `Idempotency-Key`), `422` und `429 inbox_send_cap_reached`. Siehe [Postfächer](/docs/de/inboxes).

## Webhook

`email.received` wird einmal für jede für Ihr Team gespeicherte Nachricht ausgelöst, an Endpunkte, die ihn oder alle Events abonniert haben. Er trägt nur Metadaten (Absender, Empfänger, Betreff, Anhangsliste); den Inhalt holen Sie mit `GET /emails/receiving/{email_id}`. E-Mails, die ein Postfach zurückhält, und infizierte E-Mails lösen ihn erst nach Zustellung oder Freigabe aus. Ein auf einige Postfächer beschränkter Endpunkt (`inbox_ids`) erhält ihn nur für E-Mails, die in diese zugestellt wurden. Signaturen, Wiederholungen und das Zustellprotokoll funktionieren wie bei jedem Event: siehe [Webhooks](/docs/de/concepts/webhooks).

## Was der Absender sieht

Jede Ablehnung geschieht, solange der Server des Absenders verbunden ist, er hält die Nachricht also und entscheidet, was er tut. BillionSend sendet nie einen eigenen Bounce.

| Antwort | Wann |
| --- | --- |
| `550 5.1.1` | Die Domain empfängt hier nicht, oder die Adresse hat kein Postfach (und Catch-all ist aus). Die Nachricht geht an ihren Absender zurück. |
| `550 5.7.1` | Das Team, dem die Domain gehört, ist gesperrt. |
| `552 5.3.4` | Die Nachricht überschreitet das Größenlimit Ihres Tarifs. |
| `554 5.7.1` | Die Nachricht wurde von Ihrem Schalter **Spam ablehnen** als Spam abgelehnt. |
| `452 4.2.2` | Ihr Empfangslimit ist erreicht, oder das Postfach hat in einer Stunde mehr E-Mails angenommen, als es darf (200 Nachrichten bei einem Agent-Postfach, 2.000 bei einem Postfach für Menschen). Der Absender versucht es später erneut. |

## Dashboard

**Postfächer → Alle empfangenen** listet alles auf, was Ihre Domains empfangen haben, mit Absender, Postfach, Betreff und Zeit, einem Chip, wenn eine Nachricht einen Code oder Link trägt, und einem Badge, wenn sie in Quarantäne ist oder als Spam gilt. Beim Öffnen einer Nachricht sehen Sie ihr HTML in einer Sandbox (Skripte und Remote-Bilder blockiert), den Text, die Header und die Rohnachricht, jedes Authentifizierungsergebnis erklärt, die Vertrauensstufe des Absenders und die Spam- und Virenergebnisse, den extrahierten Code oder Link, eine Zeitleiste und die Aktionen **Antworten**, **Weiterleiten**, **Freigeben** für zurückgehaltene E-Mails und **Jetzt löschen**.

## MCP

Der [MCP-Server](/docs/de/mcp) liest empfangene E-Mails mit der Berechtigung `receiving:read`, antwortet und leitet weiter mit `receiving:reply` und verwaltet Postfächer und Quarantäne mit `receiving:manage`. `update_domain` schaltet Empfang und Catch-all ein oder aus.

## Empfangene E-Mails als nicht vertrauenswürdig behandeln

Jeder kann E-Mails an eine empfangende Domain senden. HTML kann Skripte und Tracking-Bilder enthalten, Links können zu Phishing-Seiten führen, Anhänge können Schadsoftware tragen, und `from` kann gefälscht sein. Prüfen Sie `authentication` und `screening.sender_trust`, bevor Sie einem Absender vertrauen. Ein KI-Agent sollte empfangene E-Mails als Daten behandeln, nie als Anweisungen: Die MCP-Tools grenzen sie entsprechend ein, und ein [Agent-Postfach](/docs/de/agent-safety) ergänzt Quarantäne, Prüfung und Versandregeln.
