> ## Documentation Index > Fetch the complete documentation index at: https://sendmux.ai/docs/llms.txt > Use this file to discover all available pages before exploring further. # List mailbox messages > Returns a cursor-paginated list of messages for the authenticated mailbox. Requires a mailbox API key. ## OpenAPI ````yaml /openapi-app.json get /mailbox/messages openapi: 3.1.0 info: description: Programmatic access to your Sendmux email infrastructure. title: Sendmux API version: 1.0.0 servers: - description: API v1 url: https://app.sendmux.ai/api/v1 security: - bearerAuth: [] paths: /mailbox/messages: get: tags: - Mailbox API summary: List mailbox messages description: >- Returns a cursor-paginated list of messages for the authenticated mailbox. Requires a mailbox API key. operationId: mailboxListMessages parameters: - in: query name: cursor required: false schema: description: Pagination cursor — the `next_cursor` from the previous response. type: string - in: query name: limit required: false schema: description: Maximum results (default 50, max 100). maximum: 100 minimum: 1 type: integer - in: query name: folder_id required: false schema: description: Filter to messages in this folder ID. type: string - in: query name: thread_id required: false schema: description: Filter to messages in this thread ID. type: string - in: query name: q required: false schema: description: Full-text search query across message fields. type: string - in: query name: from required: false schema: description: Filter by sender email address or display name. type: string - in: query name: to required: false schema: description: Filter by To recipient email address or display name. type: string - in: query name: cc required: false schema: description: Filter by CC recipient email address or display name. type: string - in: query name: bcc required: false schema: description: Filter by BCC recipient email address or display name. type: string - in: query name: subject required: false schema: description: Filter by subject text. type: string - in: query name: body required: false schema: description: Filter by message body text. type: string - in: query name: header_name required: false schema: description: Header name to match with `header_value`. type: string - in: query name: header_value required: false schema: description: Header value to match with `header_name`. type: string - in: query name: min_size_bytes required: false schema: description: Minimum message size in bytes. minimum: 0 type: integer - in: query name: max_size_bytes required: false schema: description: Maximum message size in bytes. minimum: 0 type: integer - in: query name: keyword required: false schema: description: Require this message keyword, such as `$seen`. type: string - in: query name: not_keyword required: false schema: description: Exclude messages with this keyword. type: string - in: query name: after required: false schema: description: Filter to messages after this ISO 8601 timestamp. type: string - in: query name: before required: false schema: description: Filter to messages before this ISO 8601 timestamp. type: string - in: query name: has_attachment required: false schema: description: When true, only return messages with attachments. type: boolean - in: query name: is_unread required: false schema: description: When true, only return unread messages. type: boolean - in: query name: sort_by required: false schema: description: Message field to sort by. enum: - received_at - sent_at - subject - from - to - size_bytes type: string - in: query name: sort_direction required: false schema: description: Sort direction. enum: - asc - desc type: string - description: >- 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. in: query name: mailbox_id required: false schema: type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/MailboxMessageSummaryCursorListResponse' description: Message list '400': content: application/json: schema: $ref: '#/components/schemas/ApiError' description: Invalid query parameter '401': content: application/json: schema: $ref: '#/components/schemas/ApiError' description: Authentication required '403': content: application/json: schema: $ref: '#/components/schemas/ApiError' description: Mailbox API key required security: - bearerAuth: [] components: schemas: MailboxMessageSummaryCursorListResponse: allOf: - $ref: '#/components/schemas/SuccessEnvelope' - properties: data: items: $ref: '#/components/schemas/MailboxMessageSummary' type: array meta: $ref: '#/components/schemas/ResponseMeta' pagination: $ref: '#/components/schemas/CursorPagination' required: - data - pagination type: object unevaluatedProperties: false ApiError: additionalProperties: false properties: error: additionalProperties: false properties: code: description: Machine-readable error code enum: - invalid_parameter - missing_parameter - authentication_required - insufficient_permissions - not_found - conflict - limit_exceeded - idempotency_conflict - payload_too_large - validation_error - rate_limit_exceeded - service_unavailable - internal_error example: invalid_parameter type: string doc_url: description: Link to relevant documentation type: string errors: description: >- Accumulated per-field issues for validation errors. Only present on 400/422 responses. items: $ref: '#/components/schemas/ApiErrorDetail' type: array message: description: Human-readable error description type: string param: description: The parameter that caused the error type: string retryable: description: >- Whether the caller may safely retry this request. 4xx are typically false (except 429); 5xx are typically true. example: false type: boolean required: - code - message - retryable type: object meta: additionalProperties: false properties: request_id: example: req_clxxxxxxxxxxxxxxxxxxxxxxxxx type: string required: - request_id type: object ok: enum: - false type: boolean required: - ok - error - meta type: object SuccessEnvelope: properties: meta: additionalProperties: {} properties: {} type: object ok: enum: - true type: boolean required: - ok - meta type: object MailboxMessageSummary: additionalProperties: false properties: attachments: description: >- Attachment metadata for this message. Each item includes a short-lived `download_url`; if it expires, fetch message metadata again. items: $ref: '#/components/schemas/MailboxAttachment' type: array bcc: items: $ref: '#/components/schemas/MailboxAddress' type: array cc: items: $ref: '#/components/schemas/MailboxAddress' type: array flags: $ref: '#/components/schemas/MailboxMessageFlags' folder_ids: items: type: string type: array from: allOf: - $ref: '#/components/schemas/MailboxAddress' - type: - object - 'null' has_attachments: type: boolean id: description: Message ID type: string keywords: description: Active message keywords, including system flags and custom labels. example: - $seen - $flagged - agent_triaged items: type: string type: array preview: type: - string - 'null' received_at: type: - string - 'null' sent_at: type: - string - 'null' size_bytes: type: - integer - 'null' subject: type: - string - 'null' thread_id: type: - string - 'null' to: items: $ref: '#/components/schemas/MailboxAddress' type: array required: - id - thread_id - folder_ids - subject - preview - from - to - cc - bcc - received_at - sent_at - size_bytes - has_attachments - keywords - flags type: object ResponseMeta: additionalProperties: false properties: request_id: example: req_clxxxxxxxxxxxxxxxxxxxxxxxxx type: string required: - request_id type: object CursorPagination: additionalProperties: false properties: has_more: type: boolean next_cursor: type: string required: - has_more type: object ApiErrorDetail: additionalProperties: false properties: code: description: >- Machine-readable issue code from the validator (e.g. zod issue code). example: invalid_string type: string field: description: Dot-path of the offending request field. example: recipient.email type: string message: description: Human-readable issue description. type: string required: - field - code - message type: object MailboxAttachment: additionalProperties: false properties: content_id: description: Content ID for inline attachments, when present. type: - string - 'null' content_type: example: application/pdf type: string disposition: example: attachment type: - string - 'null' download_url: description: >- Short-lived URL for this exact attachment. Fetch it promptly; if it expires, call the message or attachment metadata endpoint again to receive a fresh URL. example: >- https://app.sendmux.ai/api/v1/mailbox/messages/msg_123/attachment-downloads/attref_abc123?download_token=... type: string filename: example: invoice.pdf type: - string - 'null' id: description: Attachment blob ID. type: string size_bytes: example: 12345 type: - integer - 'null' required: - id - filename - content_type - size_bytes - disposition - content_id type: object MailboxAddress: additionalProperties: false properties: email: example: agent@example.com format: email type: string name: example: Support type: - string - 'null' required: - email - name type: object MailboxMessageFlags: additionalProperties: false properties: answered: type: boolean draft: type: boolean flagged: type: boolean seen: type: boolean required: - seen - flagged - draft - answered type: object securitySchemes: bearerAuth: bearerFormat: API Key description: >- Sendmux API key. Use a root API key for Management API routes, or a mailbox credential for Mailbox API routes. Obtain keys from the dashboard under API Keys. scheme: bearer type: http ````