List conversations in a folder
const url = 'https://mail.work.optidata.cloud/api/mail/mailboxes/78/folders/2/conversations?page=1&filter=all';const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request GET \ --url 'https://mail.work.optidata.cloud/api/mail/mailboxes/78/folders/2/conversations?page=1&filter=all' \ --header 'Authorization: Bearer <token>'One page of the folder’s contents, newest first. What a row represents follows the caller’s own listing preference: with conversation grouping on (the default) each row is a thread, with it off each row is a single message. The page size is the caller’s conversations per page preference.
currentFilterTab echoes the applied filter and shouldDisplayFilterTab
says whether filtering is meaningful for this folder — Drafts, Important
and Scheduled ignore the filter parameter.
Authorizations
Section titled “Authorizations”Parameters
Section titled “ Parameters ”Path Parameters
Section titled “Path Parameters”Id of the mailbox. Every mailbox the caller may use is listed in their account.
Id of the folder, as returned by GET /folders.
Query Parameters
Section titled “Query Parameters”1-based page number.
The listing filters. all shows everything, read and unread filter by
state, from_company keeps mail sent from inside the company,
with_calendar_invite keeps mail carrying an invitation, and snoozed
keeps hidden threads.
Narrow the listing. all is the default; read and unread filter by
state, from_company keeps mail sent from inside the company, and
with_calendar_invite keeps mail carrying a calendar invitation. Ignored in
folders whose shouldDisplayFilterTab is false.
Responses
Section titled “ Responses ”One page of conversations.
One page of a folder’s contents.
object
Whether filtering means anything in this folder.
Whether the folder holds anything at all.
object
Id of the thread. A single-message thread reports the message id with the sign flipped.
Preview snippet of the newest message.
How an outgoing message came to be.
The state of a message or thread, as a set of booleans.
object
The user starred it.
It carries a calendar invitation.
A read receipt was requested.
The addresses of a message, grouped by role.
object
One participant of a message.
object
Display name, when one is known.
The role the address plays: f sender, t recipient, c carbon copy,
b blind copy, r reply-to.
One participant of a message.
object
Display name, when one is known.
The role the address plays: f sender, t recipient, c carbon copy,
b blind copy, r reply-to.
One participant of a message.
object
Display name, when one is known.
The role the address plays: f sender, t recipient, c carbon copy,
b blind copy, r reply-to.
One participant of a message.
object
Display name, when one is known.
The role the address plays: f sender, t recipient, c carbon copy,
b blind copy, r reply-to.
One participant of a message.
object
Display name, when one is known.
The role the address plays: f sender, t recipient, c carbon copy,
b blind copy, r reply-to.
One participant of a message.
object
Display name, when one is known.
The role the address plays: f sender, t recipient, c carbon copy,
b blind copy, r reply-to.
One participant of a message.
object
Display name, when one is known.
The role the address plays: f sender, t recipient, c carbon copy,
b blind copy, r reply-to.
One participant of a message.
object
Display name, when one is known.
The role the address plays: f sender, t recipient, c carbon copy,
b blind copy, r reply-to.
The messages of the thread. In a listing they carry ids and flags only; read the bodies with the reader operations.
A message as it appears inside a listing or a thread.
object
The RFC 5322 Message-ID header.
The state of a message or thread, as a set of booleans.
object
The user starred it.
It carries a calendar invitation.
A read receipt was requested.
The addresses of a message, grouped by role.
object
One participant of a message.
object
Display name, when one is known.
The role the address plays: f sender, t recipient, c carbon copy,
b blind copy, r reply-to.
One participant of a message.
object
Display name, when one is known.
The role the address plays: f sender, t recipient, c carbon copy,
b blind copy, r reply-to.
One participant of a message.
object
Display name, when one is known.
The role the address plays: f sender, t recipient, c carbon copy,
b blind copy, r reply-to.
One participant of a message.
object
Display name, when one is known.
The role the address plays: f sender, t recipient, c carbon copy,
b blind copy, r reply-to.
One participant of a message.
object
Display name, when one is known.
The role the address plays: f sender, t recipient, c carbon copy,
b blind copy, r reply-to.
One participant of a message.
object
Display name, when one is known.
The role the address plays: f sender, t recipient, c carbon copy,
b blind copy, r reply-to.
One participant of a message.
object
Display name, when one is known.
The role the address plays: f sender, t recipient, c carbon copy,
b blind copy, r reply-to.
One participant of a message.
object
Display name, when one is known.
The role the address plays: f sender, t recipient, c carbon copy,
b blind copy, r reply-to.
Left empty in listings; read the body with a reader operation.
A file carried by a message.
object
MIME part number, used to download it.
The cid an inline image is referenced by inside the body.
attachment or inline.
Position used to name a file that arrived without one.
Icon hint for a file-type badge.
Signed download link, populated by the reader operations. Use it as-is.
A file carried by a message.
object
MIME part number, used to download it.
The cid an inline image is referenced by inside the body.
attachment or inline.
Position used to name a file that arrived without one.
Icon hint for a file-type badge.
Signed download link, populated by the reader operations. Use it as-is.
The calendar invitation carried by the message, when there is one.
The folder-sharing offer carried by the message, when there is one.
Examples
{ "currentFilterTab": "all", "shouldDisplayFilterTab": true, "currentPage": 1, "hasNext": true, "hasPrevious": false, "hasItems": true, "items": [ { "id": "4185", "date": "2026-08-19T12:41:47.000000Z", "subject": "Re: Quarterly report", "fragment": "Thanks — attaching the signed copy…", "unreadMessages": 0, "totalMessages": 2, "type": "new", "replyServerMessageId": null, "tagIds": [], "flags": { "isUnread": false, "isFlagged": false, "hasAttachment": true, "isReplied": false, "isSentByMe": true, "isForwarded": false, "isInvite": false, "isDraft": false, "isDeleted": false, "isNotificationSent": false, "isUrgent": false, "isLowPriority": false, "isPriority": false }, "participants": { "from": [ { "name": "Jane Doe", "email": "jane.doe@acme.example", "type": "f" } ], "to": [ { "name": "John Roe", "email": "john.roe@example.com", "type": "t" } ], "cc": [], "bcc": [], "replyTo": [], "sender": [], "notification": [], "resentFrom": [] }, "messages": [] } ]}Missing, malformed or expired authentication key.
Authentication failures use an error key rather than message.
object
Examples
No bearer token sent
{ "error": "JWT passport exception: Missing bearer token in request"}The caller may not act on this mailbox, user or resource.
Generic error envelope used by policy, binding and framework failures.
object
Human-readable description of the failure.
Examples
{ "message": "This action is unauthorized."}Rate limit exceeded. Retry after the window resets.
Generic error envelope used by policy, binding and framework failures.
object
Human-readable description of the failure.
Examples
{ "message": "Too Many Attempts."}The mail platform did not answer as expected — a folder or message that
does not exist, or a transient failure. reference is the code to quote to
support and fault_code names the underlying condition. A 503 with the
same envelope means the platform is in maintenance; retry shortly.
Failure raised by the mail platform behind the API rather than by the request itself.
object
What went wrong, phrased for the end user.
Repeats the HTTP status code.
Suggested next step.
Support reference, e.g. MZ-502.
Names the underlying condition, e.g. mail.NO_SUCH_FOLDER.
Examples
Unknown folder
{ "error": "The mail server did not answer as expected, so this action could not be completed.", "status": 502, "help": "If the problem persists, contact support and inform the error code above.", "reference": "MZ-502", "fault_code": "mail.NO_SUCH_FOLDER"}Unknown message
{ "error": "The mail server did not answer as expected, so this action could not be completed.", "status": 502, "help": "If the problem persists, contact support and inform the error code above.", "reference": "MZ-502", "fault_code": "mail.NO_SUCH_MSG"}