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}/….

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.

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.