> ## Documentation Index > Fetch the complete documentation index at: https://docs.useanima.sh/llms.txt > Use this file to discover all available pages before exploring further. # Get messages 1 ## OpenAPI ````yaml /openapi.json get /messages openapi: 3.1.1 info: title: Anima API version: 0.1.0 description: >- The Anima API provides programmatic access to unified infrastructure for AI agents: create and manage agents; send and receive email; place phone calls and send/receive SMS and voice; store and retrieve vault credentials; manage agent identity; and configure webhooks for real-time events. Authenticate using a Bearer token or an API key passed via the X-API-Key header. contact: name: Anima Labs url: https://useanima.sh email: support@useanima.sh license: name: MIT url: https://opensource.org/licenses/MIT servers: - url: https://api.useanima.sh/v1 description: Production security: - BearerAuth: [] - ApiKeyAuth: [] paths: /messages: get: operationId: message.list parameters: - name: cursor in: query schema: type: string pattern: ^[cC][^\s-]{8,}$ description: Opaque cursor from a previous response to fetch the next page allowEmptyValue: true allowReserved: true - name: limit in: query schema: default: 20 type: integer minimum: 1 maximum: 100 description: Maximum number of items to return per page (1–100, default 20) allowEmptyValue: true allowReserved: true - name: agentId in: query schema: type: string pattern: ^[cC][^\s-]{8,}$ description: Filter messages by agent ID allowEmptyValue: true allowReserved: true - name: threadId in: query schema: type: string pattern: ^[cC][^\s-]{8,}$ description: Filter messages by conversation thread ID allowEmptyValue: true allowReserved: true - name: channel in: query schema: enum: - EMAIL - SMS - MMS - VOICE - WHATSAPP - RCS type: string description: Filter messages by communication channel allowEmptyValue: true allowReserved: true - name: channels in: query schema: type: array items: enum: - EMAIL - SMS - MMS - VOICE - WHATSAPP - RCS type: string description: Communication channel used for the message maxItems: 50 description: >- Filter messages by several channels at once, e.g. SMS+MMS to see a full text conversation. Takes precedence over `channel`. A single value (`?channels=SMS`) is accepted as well as the repeated (`?channels=SMS&channels=MMS`) and bracketed (`?channels[]=SMS`) forms. style: deepObject explode: true allowEmptyValue: true allowReserved: true - name: direction in: query schema: enum: - INBOUND - OUTBOUND type: string description: Filter messages by direction (inbound or outbound) allowEmptyValue: true allowReserved: true - name: status in: query schema: enum: - QUEUED - SENT - DELIVERED - FAILED - BOUNCED - BLOCKED - PENDING_APPROVAL type: string description: Filter messages by delivery status allowEmptyValue: true allowReserved: true - name: dateRange in: query schema: type: object properties: from: type: string format: date-time description: Inclusive start of the date range in ISO 8601 format to: type: string format: date-time description: Inclusive end of the date range in ISO 8601 format description: Filter messages within a date range style: deepObject explode: true allowEmptyValue: true allowReserved: true - name: inboxId in: query schema: type: string pattern: ^[cC][^\s-]{8,}$ description: >- Filter to one inbox — messages delivered to it (inbound) or sent from it (outbound). The precise way to read a single mailbox when an agent owns several. allowEmptyValue: true allowReserved: true - name: fromAddress in: query schema: type: string description: >- Filter by sender address, matched exactly (case-sensitive). On inbound mail this is the counterparty; on outbound it is the agent identity the mail was sent from. allowEmptyValue: true allowReserved: true - name: toAddress in: query schema: type: string description: >- Filter by recipient address, matched exactly (case-sensitive). Note that outbound messages store every recipient in one comma-joined value, so an exact filter matches a multi-recipient send only when given that same joined string — prefer `inboxId` to scope outbound mail to a mailbox. allowEmptyValue: true allowReserved: true - name: labels in: query schema: type: array items: type: string minLength: 1 maxLength: 64 maxItems: 50 description: >- Filter to messages carrying ALL of these labels (e.g. `urgent` + `unread` means urgent AND still unread). Case-insensitive. System labels: `unread`, `read`, `archived`, `spam`. style: deepObject explode: true allowEmptyValue: true allowReserved: true - name: includeSpam in: query schema: default: false type: boolean description: >- Include messages classified as spam on arrival. They are excluded by default. Naming `spam` in `labels` also counts as asking for it, so a deliberate spam query is never silently emptied by this default. allowEmptyValue: true allowReserved: true - name: includeArchived in: query schema: default: false type: boolean description: >- Include messages carrying the `archived` label. They are excluded by default, so archiving actually removes mail from a listing rather than only tagging it. Naming `archived` in `labels` also counts as asking for it (and returns ONLY archived mail); use this flag instead to see archived mail mixed in with the rest. allowEmptyValue: true allowReserved: true - name: deleted in: query schema: default: exclude enum: - exclude - include - only type: string description: >- How to treat messages moved to Trash. `exclude` (default) hides them, so deleted mail disappears from every ordinary listing. `only` returns nothing but Trash. `include` ignores the distinction. Deletion is reversible — see DELETE /messages/{id} and POST /messages/{id}/restore. allowEmptyValue: true allowReserved: true responses: '200': description: OK content: application/json: schema: type: object properties: items: type: array items: type: object properties: id: type: string pattern: ^[cC][^\s-]{8,}$ description: Unique identifier of the message agentId: type: string pattern: ^[cC][^\s-]{8,}$ description: ID of the agent that sent or received the message inboxId: anyOf: - type: string pattern: ^[cC][^\s-]{8,}$ - type: 'null' description: >- ID of the inbox this message belongs to — the inbox it was delivered to (inbound) or sent from (outbound). Null when no inbox backs the address: SMS/MMS/voice messages, and email sent from an email identity that has no inbox (such as a custom-domain identity added to an agent). Pass it to GET /messages?inboxId= to list one inbox's mail. channel: enum: - EMAIL - SMS - MMS - VOICE - WHATSAPP - RCS type: string description: Communication channel used direction: enum: - INBOUND - OUTBOUND type: string description: Whether the message was inbound or outbound status: enum: - QUEUED - SENT - DELIVERED - FAILED - BOUNCED - BLOCKED - PENDING_APPROVAL type: string description: Current delivery status fromAddress: type: string description: Sender address (email or phone number) toAddress: type: string description: Recipient address (email or phone number) subject: anyOf: - type: string - type: 'null' description: >- Message subject line, or null for channels that do not support subjects body: type: string description: Plain-text content of the message bodyHtml: anyOf: - type: string - type: 'null' description: >- HTML content of the message, or null if not available extractedText: anyOf: - type: string - type: 'null' description: >- Plain-text body with the quoted reply chain and signature stripped — just what this sender actually wrote. Read this instead of `body` to avoid re-reading (and paying for) the whole thread on every message. Null when nothing was extracted: non-email channels, messages your agent sent, and mail received before this field existed — so `extractedText ?? body` is always correct. Best-effort and heuristic; `body` remains the verbatim source of truth. Known weak cases: forwards and bottom-posted replies have no separable 'new' part, so this returns the full body rather than nothing. extractedHtml: anyOf: - type: string - type: 'null' description: >- HTML body with quoted reply chains removed. Same semantics as `extractedText`; `bodyHtml` stays verbatim. Quoting styles that mark the chain with a sibling element rather than wrapping it (Outlook) are not stripped here — `extractedText` still is. headers: anyOf: - type: object additionalProperties: {} - type: 'null' description: Raw message headers as key-value pairs, or null metadata: anyOf: - type: object additionalProperties: {} - type: 'null' description: Arbitrary metadata attached to the message, or null threadId: anyOf: - type: string - type: 'null' description: Thread identifier for conversation grouping, or null labels: type: array items: type: string description: >- Workflow labels on this message. Always contains exactly one of the system labels `unread` or `read`; may also contain `archived`, `spam` (the inbound spam verdict — see `includeSpam` on list/search), and any labels you add yourself. Stored lowercase, deduped, and sorted. Change them with PATCH /messages/{id}/labels. inReplyTo: anyOf: - type: string - type: 'null' description: Message ID this message is replying to, or null externalId: anyOf: - type: string - type: 'null' description: >- External identifier, or null. For email: the RFC 5322 Message-ID (bare, no angle brackets) — pass it as inReplyTo to reply in-thread. For SMS: the provider-assigned message id. deletedAt: anyOf: - type: string format: date-time - type: 'null' description: >- When this message was moved to Trash, or null if it is live. Deleted messages are hidden from listings unless `deleted` is set to `include` or `only`, and can be brought back with POST /messages/{id}/restore. Nothing purges them. sentAt: anyOf: - type: string format: date-time - type: 'null' description: >- Timestamp when the message was sent, or null if not yet sent receivedAt: anyOf: - type: string format: date-time - type: 'null' description: >- Timestamp when the message was received, or null for outbound messages readAt: anyOf: - type: string format: date-time - type: 'null' description: >- Outbound WhatsApp and RCS messages only: when the recipient's device reported the message as read. Null for inbound messages and for every other channel. Unrelated to the read and unread labels, which record whether the agent has handled a message. attachments: type: array items: type: object properties: id: type: string pattern: ^[cC][^\s-]{8,}$ description: Unique identifier of the attachment filename: type: string description: Original filename of the attachment mimeType: type: string description: >- MIME type of the attachment (e.g. application/pdf) sizeBytes: type: integer minimum: 0 description: File size in bytes storageKey: type: string description: Internal storage key for retrieving the file url: anyOf: - type: string format: uri - type: 'null' description: >- Pre-signed download URL, or null if not yet generated createdAt: type: string format: date-time description: Timestamp when the attachment was created scanStatus: enum: - PENDING - CLEAN - FLAGGED - BLOCKED type: string description: >- Content-scan verdict. BLOCKED attachments cannot be downloaded — inspect before fetching bytes. detectedMimeType: anyOf: - type: string - type: 'null' description: >- MIME type inferred from magic bytes; may differ from the declared mimeType required: - id - filename - mimeType - sizeBytes - storageKey - url - createdAt - scanStatus - detectedMimeType description: File attachment associated with a message description: File attachments associated with this message createdAt: type: string format: date-time description: Timestamp when the message record was created updatedAt: type: string format: date-time description: Timestamp when the message record was last updated required: - id - agentId - inboxId - channel - direction - status - fromAddress - toAddress - subject - body - bodyHtml - extractedText - extractedHtml - headers - metadata - threadId - labels - inReplyTo - externalId - deletedAt - sentAt - receivedAt - readAt - attachments - createdAt - updatedAt description: Full message resource representation description: Array of message resources matching the query pagination: type: object properties: nextCursor: anyOf: - type: string pattern: ^[cC][^\s-]{8,}$ - type: 'null' description: >- Cursor to pass as the `cursor` parameter to retrieve the next page, or null if no more results hasMore: type: boolean description: Whether additional pages of results are available required: - nextCursor - hasMore description: Pagination metadata for retrieving additional pages required: - items - pagination description: Paginated list of messages components: securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: JWT description: >- JWT Bearer token obtained from authentication. Pass as: Authorization: Bearer ApiKeyAuth: type: apiKey in: header name: X-API-Key description: 'API key for programmatic access. Pass as: X-API-Key: ' ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.