Searches for emails

POST/v2/users/:email/messages/query

Searches for emails in the specified user's mailbox using a query statement. Only basic information is returned by default. Use $select to specify additional fields, such as $select=internetMessageId,toRecipients.

Search results do not support returning body, internetMessageHeaders, replyTo, and isReadReceiptRequested via $select. To retrieve these fields, call the single email retrieval API.

Query Syntax

For query syntax, refer to KQL. String values can be enclosed in double quotes. A " inside double quotes must be represented as two consecutive double quotes. When double quotes are not used, the value cannot contain whitespace, double quotes, or parentheses.

Example:

date>2025-01-01T00:00:00Z AND (NOT folderId:3) AND (NOT folderId:6)
(from:"alice") OR (to:"alice<a@b.com>" AND folderId:1 AND toEmail="a@b.com")
(subject:"test") OR (attachname:"""quoteString""" AND from:alice<a@b.com>)

Supported Fields

• Common fields: date, size, tag, folderId, isRead, hasAttachments, subject, attachname, and body.
• Sender and recipient fields: from, fromEmail, to, and toEmail.
• isRead and hasAttachments support 1, 0, true, and false.
• from and to support the alias<address@example.com> format. fromEmail and toEmail use plain email addresses.

Operators

• Field operators: : (contains), = (equals), > (greater than), >= (greater than or equal to), < (less than), and < (less than or equal to).
• Logical operators: AND, OR, and NOT.
• Operator precedence: NOT > AND > OR.

Request

Path parameters

email stringrequired

User email address.

Query parameters

$select string

Body parameters

query stringrequired

Query statement.

cursor stringrequired

Starting offset identifier of the email. Its value is taken from the nextCursor field in the response. An empty string indicates starting from the beginning.

size number<int32>required

Number of emails returned. Maximum value: 100.

Response

messages object[]

Email list.

internetMessageId string

Email message ID formatted per RFC 2822 (Optional field: returned when the $select=internetMessageId query parameter is included in the URL). To request multiple fields, separate them with commas.

subject string

Email subject.

summary string

Email summary information.

priority enum

The importance of the email. Possible values: HIGH, NORMAL, LOW. Defaults to NORMAL. - PRY_HIGH: - PRY_NORMAL:

Possible values: [PRY_HIGH, PRY_NORMAL]

from object

Owner of the mailbox from which the email is sent. In most cases, this value is the same as the "sender" attribute.

email string

Email address of the person or entity.

name string

Display name of the person or entity.

toRecipients object[]

Recipients of the email (optional field: returned after adding the $select=toRecipients query parameter in the URL; use commas to separate multiple fields).

email string

Email address of the person or entity.

name string

Display name of the person or entity.

ccRecipients object[]

CC recipients of the email. (Optional field: returned by adding the $select=ccRecipients query parameter in the URL. Separate multiple fields with commas.)

email string

Email address of the person or entity.

name string

Display name of the person or entity.

bccRecipients object[]

Blind carbon copy (BCC) recipients of the email (Optional field: returned when the $select=bccRecipients query parameter is included in the URL). To request multiple fields, separate them with commas.

email string

Email address of the person or entity.

name string

Display name of the person or entity.

sender object

The account actually used to generate the email. In most cases, this value is the same as the "from" attribute. Under any circumstances, this value must correspond to the actual mailbox used (Optional field: returned after adding the $select=sender query parameter in the URL. For multiple fields, separate them with commas).

email string

Email address of the person or entity.

name string

Display name of the person or entity.

internetMessageHeaders object

Set of email headers as defined by RFC 5322.

property name* string

Set of email headers as defined by RFC 5322.

folderId string

Unique identifier of the folder to which the email belongs.

id string

Unique email identifier.

hasAttachments boolean

Indicates whether the email contains attachments (excluding inline resources).

isRead boolean

Indicates whether the email is read.

conversationId string

Unique identifier of the conversation to which the email belongs.

sentDateTime string<date-time>

Email sending time.

lastModifiedDateTime string<date-time>

Last modification time of the message (Optional field: returned when the $select=lastModifiedDateTime query parameter is added to the URL; separate multiple fields with commas).

receivedDateTime string<date-time>

Time when the recipient received the email (Optional field: returned after adding the $select=receivedDateTime query parameter to the URL. Separate multiple fields with commas.)

tags string[]

List of email tags. (Optional field: Returns when the $select=tags query parameter is added to the URL. Use commas to separate multiple fields.)

isReplied boolean

Indicates whether the email has been replied to.

isForwarded boolean

Indicates whether the email has been forwarded.

sendStatus enum

Email sending status (optional field: returned when $select=sendStatus is added to the URL; use commas to separate multiple fields).

• none:
• posting:
• partial_success:
• success:
• failed:
• unknown:

Possible values: [none, posting, partial_success, success, failed, unknown]

size number<int64>

Email size in bytes.

total number<int32>

Total number of emails.

nextCursor string

Next page cursor. $ indicates the end of the email list.

Errors

401	Access is unauthorized. Please check whether the correct authorization token is passed.
403	No API access permission. Please complete the relevant authorization on the application management page of the domain administrator.
412