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

Empfang

E-Mails auf Ihrer eigenen Domain empfangen und über die API, Webhooks und das Dashboard lesen.

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.

Es gibt zwei Wege, festzulegen, welche Adressen E-Mails annehmen: Legen Sie für eine Adresse ein Postfach an, oder schalten Sie Catch-all ein, um jede andere Adresse der Domain anzunehmen.

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

    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 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 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 oder einfaches HTTP. Diese Endpunkte brauchen einen API-Schlüssel 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.

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

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), 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 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.

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:

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.

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.

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 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 ergänzt Quarantäne, Prüfung und Versandregeln.

War diese Seite hilfreich?