Messages

Search messages

Search messages with bounded pagination. Returns UIDVALIDITY for later operations.

GET/api/v1/mailboxes/{mailboxId}/messages/

Permission read

Path parameters

mailboxIdintegerrequired

The selected mailbox ID. Email access requires a current mailbox grant.

Query parameters

folderstring

The mailbox folder name. Unicode names are supported.

Default: "INBOX" · Maximum 255 characters

limitinteger

Maximum number of items to return in this page.

Default: 25 · Minimum: 1 · Maximum: 100

cursorinteger

The continuation cursor from the previous response.

uidValiditystring

The exact UIDVALIDITY returned by the folder listing. Stale values are rejected.

fromstring

Sender identity. Must exactly match the granted mailbox address.

Maximum 254 characters

tostring

Recipient email addresses. To, Cc, and Bcc combined must not exceed 20.

Maximum 254 characters

subjectstring

The email subject, without control characters.

Maximum 200 characters

textstring

Plain-text message body.

Maximum 200 characters

sincestring · date-time

Match messages from this ISO date-time onward.

beforestring · date-time

Match messages before this ISO date-time.

seenboolean

Filter by read status.

flaggedboolean

Filter by starred status.

Responses

200Success

The requested resource or collection.

400Invalid request

Invalid input or missing idempotency key.

401Unauthenticated

Missing, expired, or revoked bearer credential.

403Forbidden

Wrong credential purpose, insufficient scope, or missing mailbox grant.

404Not found

Resource or message not found or unavailable to this integration.

409Conflict

Resource conflict, stale message reference, ambiguous submission, or idempotency conflict.

413Too large

Request or message exceeds the supported size.

429Rate limited

Rate limited. Honor Retry-After before retrying.

500Internal server error

Unexpected server error. Contact support with the request ID; inspect uncertain writes before retrying.

503Service unavailable

Integrations disabled or an upstream service unavailable.

See limits and errors for retry handling and the error envelope.

Example request

curl 'https://cherrymail.net/api/v1/mailboxes/123/messages/?limit=1' \
  -H "Authorization: Bearer $CHERRYMAIL_API_KEY"

Responseapplication/json

dataobjectrequired

Show child fields

uidValiditystringrequired

Folder UIDVALIDITY. Preserve it with the mailbox, folder, and UID when addressing a message.

messagesobject[]required

Show child fields

uidintegerrequired

Maximum: 4294967295

subjectstringrequired

fromobject[]required

Show child fields

namestring

Display name, when supplied by the message envelope.

addressstring

Envelope address when present. A group label can use an empty string; group members are flattened into this array.

toobject[]required

Show child fields

namestring

Display name, when supplied by the message envelope.

addressstring

Envelope address when present. A group label can use an empty string; group members are flattened into this array.

datestring | nullrequired

Message envelope date, or null when absent.

flagsstring[]required

IMAP flags such as \Seen and \Flagged, including custom server keywords.

sizeintegerrequired

Encoded message size in bytes.

Minimum: 0

messageIdstring | nullrequired

RFC Message-ID, or null when absent.

nextCursorinteger | nullrequired

Numeric continuation cursor for the next page; null at the end. Also preserve uidValidity.

request_idstring · uuidrequired

Request ID for support and correlation. Also returned in X-Request-ID.

Example

200 response body

{
  "data": {
    "uidValidity": "1730000000",
    "messages": [
      {
        "uid": 42,
        "subject": "Your invoice",
        "from": [
          {
            "name": "Accounts",
            "address": "accounts@example.org"
          }
        ],
        "to": [
          {
            "name": "Customer support",
            "address": "hello@example.com"
          }
        ],
        "date": "2026-10-25T17:00:00.000Z",
        "flags": [
          "\\Seen"
        ],
        "size": 2048,
        "messageId": "<invoice-1042@example.org>"
      }
    ],
    "nextCursor": 42
  },
  "request_id": "650f28e8-c344-42e4-ae43-c61539f83119"
}

The requested resource or collection.

Response headers

Cache-Control: no-store

X-Request-ID

Same request ID as the JSON body.

RateLimit-Limit: 120;w=60

Per-credential limit and window.

RateLimit-Reset: 60

Rate-limit window in seconds.

Base URL
https://cherrymail.net/api/v1

View the OpenAPI contract ↗