Search the mailbox
const url = 'https://mail.work.optidata.cloud/api/mail/mailboxes/78/search';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"page":1,"should_match_all":true,"from":"john.roe@example.com","unread":true,"content":"invoice"}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://mail.work.optidata.cloud/api/mail/mailboxes/78/search \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "page": 1, "should_match_all": true, "from": "john.roe@example.com", "unread": true, "content": "invoice" }'Search across the mailbox. Every criterion is optional except page; send
the ones you care about and leave the rest out.
By default a message needs to satisfy any criterion you send. Set
should_match_all to true to require all of them. Scope the search to
one folder with folder_id (or folder_name); omit both to search
everything.
Results follow the caller’s listing preference — threads when conversation
grouping is on, individual messages when it is off — and page with the same
page semantics as a folder listing.
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.
Request Bodyrequired
Section titled “Request Bodyrequired”The search criteria. All are optional except page; by default a message
needs to satisfy any of them, unless should_match_all is set.
object
1-based page number.
Require every criterion instead of any.
Words in the subject.
Words anywhere in the message.
Sender name or address.
Recipient name or address.
Only messages on or after this date.
Only messages on or before this date.
Restrict the search to one folder.
Restrict the search to a folder by name.
Examples
Unread mail from one sender, with an attachment word in the body
{ "page": 1, "should_match_all": true, "from": "john.roe@example.com", "unread": true, "content": "invoice"}One folder, bounded by date
{ "page": 1, "should_match_all": true, "folder_id": 2, "after": "2026-08-01", "before": "2026-08-19"}Responses
Section titled “ Responses ”One page of results.
One page of search results.
object
The matching threads, when the caller groups by conversation.
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.
Lightweight hits, carrying ids only.
object
How many results are on this page.
The folders the results live in.
A folder of a mailbox.
object
Id of the folder.
Full path from the mailbox root.
What a folder is for. Custom marks a folder the user created; the others
are the standard folders of a mailbox.
Colour, as a hex triplet.
false for the standard folders.
Sharing grants on this folder.
object
Example
{ "conversations": [ { "id": "4185", "date": "2026-08-19T12:41:47.000000Z", "type": "new", "participants": { "from": [ { "name": "Jane Doe", "email": "jane.doe@acme.example", "type": "f" } ], "to": [ { "name": "Jane Doe", "email": "jane.doe@acme.example", "type": "f" } ], "cc": [ { "name": "Jane Doe", "email": "jane.doe@acme.example", "type": "f" } ], "bcc": [ { "name": "Jane Doe", "email": "jane.doe@acme.example", "type": "f" } ], "replyTo": [ { "name": "Jane Doe", "email": "jane.doe@acme.example", "type": "f" } ], "sender": [ { "name": "Jane Doe", "email": "jane.doe@acme.example", "type": "f" } ], "notification": [ { "name": "Jane Doe", "email": "jane.doe@acme.example", "type": "f" } ], "resentFrom": [ { "name": "Jane Doe", "email": "jane.doe@acme.example", "type": "f" } ] }, "messages": [ { "id": "4186", "participants": { "from": [ { "name": "Jane Doe", "email": "jane.doe@acme.example", "type": "f" } ], "to": [ { "name": "Jane Doe", "email": "jane.doe@acme.example", "type": "f" } ], "cc": [ { "name": "Jane Doe", "email": "jane.doe@acme.example", "type": "f" } ], "bcc": [ { "name": "Jane Doe", "email": "jane.doe@acme.example", "type": "f" } ], "replyTo": [ { "name": "Jane Doe", "email": "jane.doe@acme.example", "type": "f" } ], "sender": [ { "name": "Jane Doe", "email": "jane.doe@acme.example", "type": "f" } ], "notification": [ { "name": "Jane Doe", "email": "jane.doe@acme.example", "type": "f" } ], "resentFrom": [ { "name": "Jane Doe", "email": "jane.doe@acme.example", "type": "f" } ] }, "attachments": [ { "part": "2", "filename": "report.docx", "contentType": "application/pdf", "disposition": "attachment" } ], "inlineAttachments": [ { "part": "2", "filename": "report.docx", "contentType": "application/pdf", "disposition": "attachment" } ] } ] } ], "sortBy": "dateDesc", "folders": [ { "id": "2", "name": "Inbox", "path": "Inbox/Suppliers", "role": "Inbox", "rgb": "#2F6FEB" } ]}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."}The request body or query string failed validation.
object
The first validation message.
Validation messages keyed by field name.
object
Examples
{ "message": "The conversations field is required.", "errors": { "conversation_ids": [ "The conversations field is required." ] }}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"}