Integrate the mail API and gateway handoff

The mail API is tenant-bound and uses standard Workspace permissions. Clients receive mail content only through ACL-checked Storage URLs.

This reference is for developers of mail work surfaces and private gateway adapters. It defines the authoritative HTTP and SMTP contracts. Follow Provide mail through an SMTP gateway for operational setup.

Check the contract with nucli

Use nucli so authentication, tenant selection, and permissions remain in the server contract. The built-in skill documents the safe sequence for read-only checks and explicitly approved mutations:

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

Pass request bodies with --input <file> or --input -. Do not expose subjects, bodies, addresses, notes, Storage URLs, or attachments in agent logs. Use --summary when only HTTP and response metadata are required.

Connect a work surface

  • GET /api/v1/mail/mailboxes returns visible personal and shared mailboxes.
  • GET /api/v1/mail/threads accepts class, mine, limit, and offset.
  • GET /api/v1/mail/threads/{id} returns work state and Storage references.
  • GET /api/v1/mail/search?q=… uses the permission-checked blind index.
  • POST /api/v1/mail/send stores RFC822 and its projection encrypted and queues the same Storage reference once per envelope recipient. Pass readable attachments as attachmentObjectIds.
  • /api/v1/mail/drafts manages encrypted, author-only drafts.
  • /api/v1/mail/threads/{id}/notes manages encrypted internal notes.
  • POST /api/v1/mail/threads/{id}/assist returns only an assistive summary and reply suggestion through the MAIL_ASSIST policy task.

Seen state, move, take/assignment, screening, follow-up, and explicit Inbox projection commands live under /api/v1/mail/threads/{id}/….

Never copy subject, body, or attachments into logs, audit metadata, Conversation fields, or queue payloads. Use the returned Storage references.

Interpret SMTP responses

The private listener validates recipients during RCPT TO:

  • 250: the recipient is active and routable.
  • 550: the domain, address, mailbox, or bounce recipient is unavailable.
  • 451: a temporary lookup or Storage failure; the gateway must retry.
  • 250 stored after DATA: original, projection, ACL, blind index, and intake ledger are durably published.

The client must connect with TLS 1.3 and an allowlisted mTLS certificate. Do not expose this contract as a public SMTP listener.

The integration succeeds when an authorized client receives only its granted mailboxes and threads, an unauthorized request fails without content details, and the gateway removes a message from its queue only after 250 stored. For outbound mail, distinguish stored, queued, delivered, and DSN-failed recipient state.