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
-
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 beiexample.combleiben also bei Ihrem jetzigen Anbieter. -
Fügen Sie genau diesen Namen unter Domains hinzu und verifizieren Sie ihn, wie beim Senden. Die Verifizierung von
example.comdeckt dessen Subdomains nicht ab. -
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
409beantwortet. -
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.commx1.billionsend-dns.com10MX inbound.example.commx2.billionsend-dns.com10Jeder 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.
-
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.
-
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 vonorders@. - Bei eingeschaltetem Catch-all auch jede andere Adresse:
support@,invoices@,reply+ticket-4821@. Lesen Siereceived_forin 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_forlistet die Adressen Ihrer Domains auf, an die die Nachricht tatsächlich zugestellt wurde, Bcc eingeschlossen.toundccsind nur das, was die Header behaupten, richten Sie das Routing also nachreceived_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.comwerden 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.4abgelehnt. - 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,headersundrawalsnull,attachmentsist 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
beforeodersincezä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_waitsbeantwortet. - 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_score25 bis 49) oderfail(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(mitvirus_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) odernull, wenn kein Scan lief. Infizierte E-Mails werden zurückgehalten: Sie lösen keinemail.receivedaus, bis ein Mensch sie im Dashboard freigibt, und ihre Downloads antworten mit410 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=cidbehältcid:-Verweise, die Sie mit dercontent_idjedes Anhangs abgleichen.textkommt ohne unsichtbare Zeichen;htmlist exakt wie empfangen.extracted_textist der Antwortteil der Nachricht, bereinigt um Text, den ein Mensch nicht sehen kann.extractedträ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;okmittext;unsupportedfür andere Dateien (ältere.docund.xls, PowerPoint, Bilder);encryptedfür eine passwortgeschützte Datei;too_largeüber 25 MB oder wenn das Lesen mehr Speicher bräuchte als erlaubt;unreadablefür eine beschädigte Datei;timeoutoderfailed, wenn das Lesen nicht abgeschlossen wurde.nullfü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 namepro 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
textoderhtml,subject,cc,bccundreply_allentgegen. Die Antwort geht an denReply-Toder Nachricht oder sonst an ihren Absender. - Weiterleiten nimmt
to,cc,bcc, eine Notiz,subjectundmodeentgegen:inline(Standard) zitiert das Original,attachmenthängt es alsforwarded_message.emlan. fromist jede Adresse auf einer verifizierten Domain Ihres Teams; standardmäßig die Adresse des Postfachs, das die Nachricht erreicht hat.requires_approval: truehä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.