Email

Mailboxes (IMAP/SMTP, Gmail, Microsoft 365) live under /email/api/v1.

Connecting a mailbox

POST /email/api/v1/accounts takes:

• provider: MAIL with the IMAP and SMTP servers and passwords. They are checked before anything is created: a refused login is 401 errors/invalid_credentials. GET …/accounts/autoconfig finds the servers for an address, and POST …/accounts/verify checks them without creating anything.
• GOOGLE_OAUTH or OUTLOOK with your OAuth app's tokens: register the app once with POST /email/api/v1/oauth_apps, then pass its oauth_app_id.

Every host you name must be public. The answer is 201; CREATION_SUCCESS follows when the mailbox is connected. Events start from then: no history is replayed. Connects, reconnects and login checks together are limited to 120 per 10 minutes for your company (429, with retry_after_ms).

Sending

POST /email/api/v1/emails sends, as JSON or multipart (attachments as file parts): at most 500 recipients and 25 MB of attachments. The answer is 201: the mail is queued, and mail_sent follows when it has left.

• Idempotency-Key header: a retry with the same key answers the first send instead of sending again (keys are per mailbox).
• from may set a display name; its address must be the mailbox's own (422 errors/send_as_denied otherwise).
• reply_to is the email (emm_… or provider id) this one answers: it threads the reply. It is not a Reply-To header (that one goes in custom_headers).
• tracking_id (the Message-ID without <>) ties the send to its mail_sent event, its opens and clicks, and its bounces (gateway.mail_bounced), complaints (gateway.mail_complaint) and failures (gateway.mail_failed).

Reading

GET /email/api/v1/emails lists one folder at a time, newest first, metadata only (include_body=true adds the bodies, 25 a page at most), and GET /email/api/v1/emails/{id} reads one in full. Replies arrive as mail_received events.

An email id (emm_…) and a folder id (emf_…) carry their mailbox; a provider's own ids (provider_id) are accepted with account_id. An IMAP mail's provider_id changes when it moves folder.