Agent-Mailboxen

Eine Agent-Mailbox ist ein adressierbares Postfach, das Ihr Code über die API verwaltet. Lesen und filtern Sie Threads, antworten Sie auf Nachrichten oder verfassen Sie neue E-Mails, ohne einen IMAP-Server zu betreiben oder rohes MIME zu parsen.

Eine Mailbox liegt auf der gemeinsamen inbox.ai-Domain oder auf Ihrer eigenen empfangsfähigen Sendedomain. Ihre Adresse wird im Moment der Erstellung beansprucht und bleibt Ihnen zugeordnet: Der Local Part ist für Ihren Workspace reserviert und wird niemals an jemand anderen vergeben, auch nicht nach dem Löschen der Mailbox.

Adressen

Jede Mailbox hat eine Adresse, {local_part}@inbox.ai. Sie erhalten eine Adresse auf zwei Wegen:

Generiert: Lassen Sie den Local Part weg, und wir erzeugen einen kollisionsfreien für Sie (a7f3k2@inbox.ai). Immer verfügbar.
Benutzerdefiniert: Fordern Sie einen bestimmten Local Part an (support@inbox.ai). Benutzerdefinierte Handles sind global eindeutig, werden in der Reihenfolge der Anfragen vergeben und sind nur im Rahmen eines kostenpflichtigen Tarifs verfügbar; ein kostenloser Workspace verwendet generierte Adressen.

Eine Adresse ist nach dem Erstellen unveränderlich. Um sie zu ändern, erstellen Sie eine neue Mailbox und löschen die alte. Der alte Local Part wird 30 Tage lang gehalten (sein Wiederherstellungsfenster), bevor er erneut beansprucht werden kann, und bleibt Ihrem Workspace vorbehalten.

Threads und Nachrichten

Empfangene und gesendete E-Mails werden in Threads gruppiert, einer pro Konversation. Ein Thread enthält die beteiligten Adressen, einen Ungelesen-Zähler, die Richtung der letzten Nachricht (inbound oder outbound) und den Zeitstempel der jüngsten Aktivität. Antworten werden in den Thread einsortiert, auf den sie sich beziehen; eine neue Nachricht eröffnet einen neuen Thread.

Jede Nachricht stellt Header, extrahierten Klartext ohne Zitatverlauf und Anhänge bereit. Originale Nachrichtentexte sind 30 Tage lang verfügbar; Raw-MIME ist nur für empfangene Nachrichten verfügbar. Nachrichten-IDs tragen ein Richtungspräfix: rem_ für eine empfangene Nachricht, em_ für eine gesendete.

Was in die Inbox gelangt

Zwei Kontrollen stehen vor der Inbox, beide prüfen gegen den Envelope-Absender statt gegen den fälschbaren From:-Header:

Empfangsrichtlinie: der mailboxweite Standard.
- open akzeptiert alles, was die Authentifizierung besteht.
- replies_only akzeptiert nur E-Mails, die einen bereits vorhandenen Thread in der Mailbox fortsetzen.
- allowlist akzeptiert nur Absender, die Ihre Regeln erlauben, plus Antworten auf einen bestehenden Thread.
- drop verwirft alles, ohne Ausnahme.
Empfangsregeln: absenderbezogene Allow- oder Block-Einträge, abgeglichen auf eine vollständige Adresse oder eine Domain (eine Domain-Regel erfasst auch deren Subdomains). Ein Block hat immer Vorrang vor einem Allow.

E-Mails, die eine Regel blockiert oder die DMARC nicht bestehen, werden trotzdem in der Mailbox gespeichert und bleiben lesbar: Sie werden außerhalb der Inbox abgelegt statt verworfen und lösen keinen Webhook aus. Die einzige Ausnahme ist eine Mailbox mit der Einstellung drop, die alles sofort verwirft statt abzulegen.

Senden

Eine Mailbox sendet auf zwei Wegen über die API: Antworten auf eine Nachricht (die ausgehende Nachricht wird in diesen Thread einsortiert) oder Verfassen einer neuen Nachricht (die einen neuen Thread eröffnet). Im Dashboard können Sie eine Nachricht öffnen und Weiterleiten wählen, um deren Originaltext und Anhänge innerhalb des 30-Tage-Fensters an neue Empfänger zu senden. E-Mails werden von der eigenen Adresse der Mailbox gesendet, mit dem Anzeigenamen und der Standard-Reply-To-Adresse, die Sie konfiguriert haben. Der Zustellstatus wird an die gesendete Nachricht zurückgemeldet, sodass Sie sehen, ob eine Antwort zugestellt wurde oder zurückkam.

Events

Abonnieren Sie die email_mailbox.*-Webhook-Familie, um einen Agenten ohne Polling zu steuern: email_mailbox.message_received (eingehende E-Mail hat die Inbox erreicht), email_mailbox.thread_created und die Zustellstatus-Events für von Ihnen gesendete Nachrichten. Nur Inbox-E-Mails werden weitergeleitet; Spam und regelblockierte E-Mails werden stillschweigend gespeichert, sodass eine überflutete Mailbox keine Webhook-Flut auslöst. Inbox-E-Mails lösen auch das Standard-Event email.received aus, sodass eine bestehende Inbound-Integration weiter funktioniert.

Für eine Live-Ansicht ohne Webhook-Infrastruktur verbinden Sie sich mit GET /v1/email/mailboxes/{mailbox_id}/events. Der SSE-Stream sendet Event-Typ, Thread-ID und Nachrichten-ID für Mailbox-Aktivitäten, einschließlich Spam und blockierter Eingänge. Rufen Sie vollständige Nachrichten mit diesen IDs ab. Der Stream wiederholt keine Events nach einer Unterbrechung. Verwenden Sie Webhooks für dauerhafte Zustellung und die List-Endpunkte, um nach einer Lücke aufzuholen.

Aufbewahrung und Löschung

Die Aufbewahrungsstufe einer Mailbox bestimmt, wie lange Sie Nachrichten-Header, extrahierten Text und Mailbox-Anhänge lesen können, gemessen ab dem Senden oder Empfangen. Der Standard ist 30 Tage. Wenn Ihr Plan 90-Tage- oder 365-Tage-Aufbewahrung umfasst, setzen Sie retention_tier beim Erstellen oder Aktualisieren. Eine Stufe, die Ihr Plan nicht umfasst, wird mit E17048 abgelehnt.

Inhalt oder Aktion	Aufbewahrungsfenster
Nachrichten-Header, extrahierter Text und Mailbox-Anhänge	Gewählte Stufe: 30, 90 oder 365 Tage
Originale HTML- und Klartext-Nachrichtentexte	30 Tage auf jeder Stufe
Raw-MIME für empfangene Nachrichten	30 Tage auf jeder Stufe; gesendete Nachrichten haben kein gespeichertes Raw-MIME
Weiterleiten einer Nachricht im Dashboard	Erfordert Originalinhalt innerhalb seines 30-Tage-Fensters
Extrahierten Text lesen oder mit neuem Inhalt antworten	Verfügbar, solange die Nachricht aufbewahrt wird

Beispiel: An Tag 40 hat eine Nachricht in einer 90-Tage-Mailbox weiterhin lesbaren, durchsuchbaren extrahierten Text und aufbewahrte Anhänge. Sie können mit neuem Inhalt antworten, aber den Originaltext nicht öffnen, das Raw-MIME nicht herunterladen und die Nachricht nicht weiterleiten. Extrahierter Text ist auf 64 KiB pro Nachricht begrenzt und kann Teile des Originals auslassen. Anhänge, die vor dem Aktivieren der erweiterten Anhang-Aufbewahrung gespeichert wurden, behalten ihre ursprüngliche Ablaufzeit von ungefähr 31 Tagen; ein Stufenwechsel migriert sie nicht. Ein Anheben der Stufe kann bereits gelöschte Inhalte nicht wiederherstellen.

Nachrichten werden von der API nicht mehr zurückgegeben, wenn ihre Aufbewahrung abläuft. Ein stündlicher Durchlauf verarbeitet die Löschung im Hintergrund; die physische Bereinigung kann hinter dem Ablauf von API zurückbleiben.

Das Herabsetzen der Stufe wirkt sich sofort auf Lesezugriffe aus: Alles, was älter ist als der neue Grenzwert, wird sofort nicht mehr zurückgegeben. Sie haben zehn Minuten, um es rückgängig zu machen, und zehn Minuten ist die einzige Garantie: Setzen Sie die Stufe innerhalb dieses Fensters wieder hoch, geht nichts verloren. Danach werden die verwaisten Nachrichten zur Löschung freigegeben, und der nächste stündliche Durchlauf entfernt sie – ein späteres Hochsetzen stellt nur wieder her, was der Durchlauf noch nicht erreicht hat.

Das Hochsetzen auf eine in Ihrem Plan enthaltene Stufe wird jederzeit akzeptiert, auch während eine frühere Änderung noch angewendet wird. Das Hintergrund-Update ist unabhängig vom Zehn-Minuten-Rückgängig-Fenster. Ein erneutes Herabsetzen wird akzeptiert, nachdem die erste Änderung jede gespeicherte Nachricht aktualisiert hat. Das Update startet alle zehn Minuten und kann bei großen Mailboxen Stunden dauern. Bis es abgeschlossen ist, gibt API den Fehler E17050 zurück; versuchen Sie es später erneut.

Wenn Ihr Plan ein begrenztes Mailbox-Speicherkontingent vorsieht, wird ein Kontingent von allen aktiven oder wiederherstellbaren Mailboxen geteilt. Jede Mailbox meldet ihren Anteil als size_bytes. Ein Plan ohne begrenztes Kontingent bietet unbegrenzten Mailbox-Speicher. Sobald die Mailboxen zusammen ein begrenztes Kontingent erreichen, wird das Senden mit E17049 abgelehnt, bis Sie in einer beliebigen Mailbox Speicher freigeben.

Das Löschen einer Mailbox stoppt den E-Mail-Empfang sofort. Die Mailbox kann 30 Tage lang wiederhergestellt werden, während die normale Aufbewahrungsfrist weiterläuft. Nach 30 Tagen entfernt die endgültige Löschung die Mailbox und ihre verbleibenden Nachrichten. Sobald die endgültige Löschung beginnt, wird eine Wiederherstellung abgelehnt, auch wenn die Bereinigung noch läuft. Die Adresse bleibt Ihrem Workspace vorbehalten.

Nächste Schritte

Ihre erste Mailbox beanspruchen: der API-Happy-Path vom Erstellen bis zur Antwort.
Mit KI bauen: Mailboxen über den MCP-Server von einem Agenten aus steuern.

Verwandte Ressourcen