Mail-API und Gateway-Handoff integrieren

Die Mail-API arbeitet tenantgebunden und verwendet die normalen Workspace-Berechtigungen. Clients erhalten Mailinhalt ausschließlich über ACL-geprüfte Storage-URLs.

Diese Referenz richtet sich an Entwickler von Mail-Arbeitsflächen und privaten Gateway-Adaptern. Sie beschreibt die autoritativen HTTP- und SMTP-Verträge; die betriebliche Einrichtung führt Mail mit einem SMTP-Gateway bereitstellen.

Vertrag mit nucli prüfen

Nutzen Sie nucli, damit Authentisierung, Tenant und Berechtigungen im Serververtrag bleiben. Der eingebaute Skill dokumentiert die sichere Reihenfolge für lesende Prüfungen und ausdrücklich freigegebene Mutationen:

bash
nucli skills show mail
nucli --tenant <tenant> whoami --scopes
nucli --tenant <tenant> api GET /api/v1/mail/mailboxes --summary
nucli --tenant <tenant> api GET \
  '/api/v1/mail/threads?class=screener&limit=25' --summary

Übergeben Sie Request-Bodies mit --input <datei> oder --input -. Geben Sie Betreff, Body, Adressen, Notizen, Storage-URLs oder Anhänge nicht in Agentenlogs aus. Nutzen Sie --summary, wenn nur HTTP- und Response-Metadaten erforderlich sind.

Arbeitsfläche anbinden

  • GET /api/v1/mail/mailboxes liefert sichtbare persönliche und gemeinsame Postfächer.
  • GET /api/v1/mail/threads filtert nach class, mine, limit und offset.
  • GET /api/v1/mail/threads/{id} liefert Arbeitszustand und Storage-Referenzen.
  • GET /api/v1/mail/search?q=… sucht über den berechtigungsgeprüften Blindindex.
  • POST /api/v1/mail/send speichert RFC822 und Projektion verschlüsselt, stellt pro Envelope-Empfänger denselben Storage-Verweis in die Queue. Berechtigte Anhänge werden als attachmentObjectIds übergeben.
  • /api/v1/mail/drafts verwaltet verschlüsselte, autorbezogene Entwürfe.
  • /api/v1/mail/threads/{id}/notes verwaltet verschlüsselte interne Notizen.
  • POST /api/v1/mail/threads/{id}/assist liefert ausschließlich eine assistive Zusammenfassung und einen Antwortvorschlag über MAIL_ASSIST.

Mutationen für Seen, Verschieben, Übernehmen/Zuweisen, Screener, Follow-up und explizite Inbox-Projektion liegen unter /api/v1/mail/threads/{id}/….

Importierte Quellordner werden über GET /api/v1/mail/imported-containers gelistet. GET /api/v1/mail/imported-containers/{containerID}/thread-pages liefert daraus stabile, ACL-geprüfte Seiten. Die Ordner sind eine schreibgeschützte Herkunftssicht; normale Arbeitsklassen bleiben davon getrennt.

Mail sicher verfassen und senden

Der interaktive Composer verwendet diese Reihenfolge:

  1. GET /api/v1/mail/compose/readiness prüft die lokalen Voraussetzungen.
  2. GET /api/v1/mail/compose/templates listet die wirksamen Vorlagen aus dem Namespace mailbox/compose. Der Endpunkt unterstützt locale, q, count, page oder offset und die feste Sortierung key ASC.
  3. POST /api/v1/mail/compose/preview rendert die vollständige Nachricht.
  4. POST /api/v1/mail/compose/send erhält denselben Request zusammen mit dem zurückgegebenen previewDigest.

Der Digest ist zehn Minuten lang an Tenant, Identity und Eingabe gebunden. Vor dem Versand rendert der Server erneut. Ein wiederholter identischer bestätigter Request liefert dasselbe Ergebnis, ohne eine zweite Nachricht anzulegen. Ändert sich ein Feld, ist eine neue Vorschau erforderlich.

Anhänge benötigen Leserechte, denselben Tenant, einen freigegebenen fachlichen Storage-Kontext und bei aktiver Prüfung einen zulässigen Scanstatus. Betreff, Body und Anhänge dürfen nicht in Logs, Audit-Metadaten, Conversation-Felder oder Queue-Payloads kopiert werden. Verwenden Sie immer die zurückgegebenen Storage-Referenzen.

SMTP-Antworten interpretieren

Der private Listener prüft Empfänger bereits bei RCPT TO:

  • 250: Empfänger ist aktiv und geroutet.
  • 550: Domain, Adresse, Postfach oder Bounce-Empfänger ist nicht verfügbar.
  • 451: temporärer Lookup- oder Storage-Fehler; das Gateway muss erneut zustellen.
  • 250 stored nach DATA: Original, Projektion, ACL, Blindindex und Intake-Ledger sind dauerhaft veröffentlicht.

Der Client verbindet sich ausschließlich per TLS 1.3 mit einem erlaubten mTLS-Zertifikat. Verwenden Sie diesen Vertrag nicht als öffentlichen SMTP-Listener.

Providerneutralen Mailtransfer anbinden

Der Adapter benötigt mail:import; dieses Recht gewährt keinen Lese-, Such- oder Exportzugriff auf Mailinhalte. Die Aufrufe erfolgen in dieser Reihenfolge:

  • POST /api/v1/mail/transfer/sessions
  • POST /api/v1/mail/transfer/sessions/{sessionID}/containers
  • POST /api/v1/mail/transfer/sessions/{sessionID}/batches
  • PUT /api/v1/mail/transfer/batches/{batchID}/items
  • POST /api/v1/mail/transfer/batches/{batchID}/reconcile
  • GET /api/v1/mail/transfer/batches/{batchID} bis zum Status ready
  • POST /api/v1/mail/transfer/batches/{batchID}/publish
  • GET /api/v1/mail/transfer/batches?limit=50 für die mandantenbezogene Betriebsübersicht ohne Quellkennungen oder Mailinhalt

Der Item-Request ist multipart/form-data. Der erste Part heißt metadata und enthält JSON, der zweite Part heißt bei upsert zwingend message mit Content-Type: message/rfc822. Die Metadaten führen unter anderem containerId, sourceItemKey, containerRevisionHash, contentHash, operation, direction, sizeBytes, internalDate und die Flags seen, flagged, answered, draft und deleted. Bei tombstone endet der Request nach dem Metadaten-Part.

Manifest Version 1 verwendet ausschließlich UTF-8 und kleingeschriebene SHA-256-Hexwerte. Für jedes Element berechnet der Adapter zunächst:

text
leaf = sha256(sourceItemKey + NUL + operation + NUL + contentHash + NUL
  + decimalSizeBytes + NUL + direction + NUL + utcInternalDate + NUL
  + seen + NUL + flagged + NUL + answered + NUL + draft + NUL + deleted)

utcInternalDate ist als UTC-Wert nach RFC 3339 Nano formatiert. Boolesche Werte stehen kleingeschrieben als true oder false im kanonischen Text. Opake Quellkennungen dürfen kein U+0000 enthalten, weil NUL die Felder trennt. Die Leaf-Hexwerte werden byteweise aufsteigend sortiert, mit LF verbunden und erneut mit SHA-256 gehasht. Das ist der expectedManifestHash des Ordners. Für den Batch wird je Ordner die Zeile containerRevisionHash:folderManifestHash:itemCount:byteCount gebildet; diese Zeilen werden ebenfalls sortiert, mit LF verbunden und gehasht. Ein leerer Satz ist der SHA-256-Hash der leeren Bytefolge. Der Server speichert Quellschlüssel nur als geheimnisgebundenen HMAC, der Adapter kann die öffentlichen Manifest-Hashes trotzdem selbst berechnen.

Snapshot oder Delta exportieren

Der Export benötigt mail:export und zusätzlich mindestens Leserechte auf dem Postfach. POST /api/v1/mail/mailboxes/{mailboxID}/exports akzeptiert fromRevision; 0 erzeugt einen vollständigen Snapshot. Der Response enthält den festgehaltenen Wert throughRevision. Anschließend wird GET /api/v1/mail/exports/{exportID} abgefragt, bis der Job completed ist und eine artifactUrl liefert. Das verschlüsselt gespeicherte nucleus-mail-transfer.v1-Tar enthält manifest.json sowie unveränderte RFC822-Dateien. Delta-Grenzen basieren ausschließlich auf monotonen Mailboxrevisionen, nicht auf Zeitstempeln.

Die artifactUrl zeigt auf den geschützten Mail-Endpunkt GET /api/v1/mail/exports/{exportID}/artifact. Jeder Download prüft erneut die anfordernde Identität, mail:export, die aktuelle Mailbox-ACL und die Ablaufzeit. Exporte dürfen nicht in Logs, Tickets oder ungeschützte Zwischenablagen kopiert werden.

Die Integration ist erfolgreich, wenn ein berechtigter Client nur seine freigegebenen Mailboxen und Threads erhält, ein unberechtigter Zugriff ohne Inhaltsdetails abgewiesen wird und das Gateway erst nach 250 stored aus seiner Queue entfernt. Beim Versand muss der Client gespeicherte, in die Queue eingestellte, zugestellte und per DSN fehlgeschlagene Empfängerzustände unterscheiden.