Mailbox API

List mailbox messages

Changed on

Returns a cursor-paginated list of messages for the authenticated mailbox. Requires Mailbox API access.

get/mailbox/messages

Request

  • Base URL: https://app.sendmux.ai/api/v1
  • URL: https://app.sendmux.ai/api/v1/mailbox/messages
  • Auth: one of:
    • HTTP bearer
    • OAuth 2 (authorization code, authorization URL https://app.sendmux.ai/oauth/authorize, token URL https://app.sendmux.ai/oauth/token, scopes: mailbox.read)

Query parameters

cursorstring

Pagination cursor — the next_cursor from the previous response.

limitinteger

Maximum results (default 50, max 100).

folder_idstring

Filter to messages in this folder ID.

thread_idstring

Filter to messages in this thread ID.

qstring

Full-text search query across message fields.

fromstring

Filter by sender email address or display name.

tostring

Filter by To recipient email address or display name.

ccstring

Filter by CC recipient email address or display name.

bccstring

Filter by BCC recipient email address or display name.

subjectstring

Filter by subject text.

bodystring

Filter by message body text.

header_namestring

Header name to match with header_value.

header_valuestring

Header value to match with header_name.

min_size_bytesinteger

Minimum message size in bytes.

max_size_bytesinteger

Maximum message size in bytes.

keywordstring

Require this message keyword, such as $seen.

not_keywordstring

Exclude messages with this keyword.

afterstring

Filter to messages after this ISO 8601 timestamp.

beforestring

Filter to messages before this ISO 8601 timestamp.

has_attachmentboolean

When true, only return messages with attachments.

is_unreadboolean

When true, only return unread messages.

sort_by'received_at' | 'sent_at' | 'subject' | 'from' | 'to' | 'size_bytes'

Message field to sort by.

sort_direction'asc' | 'desc'

Sort direction.

mailbox_idstring

Mailbox public ID to target when the credential grants access to more than one mailbox. Omit when the credential is scoped to exactly one mailbox.

Response

Message list

oktrue required

Example response

{
  "data": [
    {
      "attachments": [
        {
          "content_type": "application/pdf",
          "disposition": "attachment",
          "download_url": "https://app.sendmux.ai/api/v1/mailbox/messages/msg_123/attachment-downloads/attref_abc123?download_token=...",
          "filename": "invoice.pdf",
          "size_bytes": 12345
        }
      ],
      "bcc": [
        {
          "email": "agent@example.com",
          "name": "Support"
        }
      ],
      "cc": [
        {
          "email": "agent@example.com",
          "name": "Support"
        }
      ],
      "from": {
        "email": "agent@example.com",
        "name": "Support"
      },
      "keywords": [
        "$seen",
        "$flagged",
        "agent_triaged"
      ],
      "to": [
        {
          "email": "agent@example.com",
          "name": "Support"
        }
      ]
    }
  ]
}

Changes

  • b42ce87003aeRevision changes
    • info

      removed subschema #2 from the /// response property allOf list for the response status

    • info

      added subschema #2 to the /// response property anyOf list for the response status

  • 86e7afbe39ffRevision changes
    • info

      added the optional property // to the response with the status