> ## 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.
# Post messagessearch
## OpenAPI
````yaml /openapi.json post /messages/search
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/search:
post:
operationId: message.search
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
query:
type: string
minLength: 1
description: >-
Full-text search query matched against subject, body, and
addresses. Supports web-search syntax: bare words are AND-ed
(`invoice overdue`), `"quoted phrases"` match in order,
`-word` excludes, and `or` alternates (`invoice or
receipt`). Words are stemmed, so `approving` matches
`approval`. Results are ranked by relevance, with subject
matches weighted above body matches above address matches.
For meaning-based rather than keyword matching, use POST
/messages/search/semantic instead.
filters:
default: {}
type: object
properties:
agentId:
type: string
pattern: ^[cC][^\s-]{8,}$
description: Filter results by agent ID
channel:
enum:
- EMAIL
- SMS
- MMS
- VOICE
- WHATSAPP
- RCS
type: string
description: Filter results by communication channel
direction:
enum:
- INBOUND
- OUTBOUND
type: string
description: Filter results by message direction
status:
enum:
- QUEUED
- SENT
- DELIVERED
- FAILED
- BOUNCED
- BLOCKED
- PENDING_APPROVAL
type: string
description: Filter results by delivery status
dateRange:
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 results within a date range
inboxId:
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.
fromAddress:
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.
toAddress:
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.
labels:
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`.
includeSpam:
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.
includeArchived:
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.
deleted:
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.
description: Optional filters to narrow search results
pagination:
default:
limit: 20
type: object
properties:
cursor:
type: string
pattern: ^[cC][^\s-]{8,}$
description: >-
Opaque cursor from a previous response to fetch the next
page
limit:
default: 20
type: integer
minimum: 1
maximum: 100
description: >-
Maximum number of items to return per page (1–100,
default 20)
description: Pagination parameters for the search results
required:
- query
description: >-
Request body for searching messages with full-text query and
optional filters
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
snippet:
anyOf:
- type: string
- type: 'null'
description: >-
Excerpt of the body around the matched terms, with
each match wrapped in `…`. Lets an
agent judge relevance without fetching the full
body. Null when the query matched only the subject
or an address, so there is nothing in the body to
excerpt. Not sanitized: it is a fragment of the raw
body, which may itself contain markup.
rank:
type: number
description: >-
Relevance score for this query. Ordering-only —
comparable between hits of the SAME search,
meaningless across different searches, and not a
percentage. Results are already sorted by it,
descending.
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
- snippet
- rank
description: >-
A message matching a full-text search, with its
relevance score and excerpt
description: >-
Matching messages, most relevant first (not most recent
first)
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: Ranked, paginated full-text search results
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.