Overview

Mailboxes, folders, conversations, messages and sending for the Optiwork suite.

Optiwork Mail API v2026.08.19.0956

The Optiwork Mail API covers the e-mail surface of the Optiwork suite: the folders of a mailbox, the conversations and messages inside them, the drafts you compose and the scheduled deliveries they can become, plus the everyday operations around them — reading, flagging, tagging, moving, archiving, searching, snoozing, answering calendar invitations and reviewing quarantined spam.

Base URL

All endpoints are served under the fixed Mail host: https://mail.work.optidata.cloud/api.

Authentication

Every endpoint requires a Bearer JWT passport, except GET /ping and the signed attachment-download link, which carries its own signature in the query string. Your personal passport is available in Optiwork at https://work.optidata.cloud/user/settings/security (My account > Profile > Security), where it is shown as the authentication key. Send it on every request:

Authorization: Bearer opk_xxxxxxxxxxxxxxxxxxxxxxxx
Accept: application/json

Passports are short-lived; when a request returns 401, get a fresh authentication key from the same settings page and retry.

Conventions

Almost every endpoint is scoped to a mailbox, addressed by its numeric id in the path. A mailbox you may not read answers 403.
A folder is addressed by its id, a string of digits. The standard folders carry a role (Inbox, Sent, Drafts, Archives, Junk, Trash, Snoozed, Scheduled, Important, SharedWithMe); folders you create carry Custom.
A conversation groups the messages of one thread. A thread with a single message reports a negative id — the id of that message with the sign flipped — while a real multi-message thread reports a positive id. Use the id exactly as returned.
Listing endpoints page with page (1-based); the page size comes from the caller’s own conversations per page preference. They answer with hasNext / hasPrevious rather than a total.
Batch operations take an array of ids and apply the change to all of them. They echo the ids back so a caller can reconcile.
Timestamps are ISO-8601 (e.g. 2026-08-19T12:45:28.000000Z). Values you send for scheduling and snoozing are interpreted in the timezone you send alongside them.
Sending is a two-step flow: save a draft, then send it. Every send operation identifies the body it is sending by draft_id.
Validation failures return 422 with a per-field errors map. Failures raised further down — a folder or message that cannot be read — return 502 (or 503 while the mail platform is in maintenance) with an { "error", "status", "help", "reference", "fault_code" } envelope.
Requests are rate limited per authenticated user; exceeding the limit returns 429.

Optidata — Optiwork Platform Team

https://www.optidata.cloud

Information

OpenAPI version: 3.1.0

Authentication

bearerAuth

The authentication key (JWT passport) from My account > Profile > Security at work.optidata.cloud/user/settings/security.

Security scheme type: http

Bearer format: JWT

Overview

Optiwork Mail API v2026.08.19.0956

Base URL

Authentication

Conventions

Operations

Authentication

bearerAuth