> ## Documentation Index
> Fetch the complete documentation index at: https://aisa.one/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Search All Threads
> Full-text search over threads in every inbox in the account.
Full-text search over threads in **every inbox in the account**. Returns `count`, `limit`, `next_page_token` and `threads`; page with `next_page_token`. Same fields as `get_agentmail_threads`, which is the one to use for everything in date order. This is the organization-wide view spanning every inbox in the account. Every AIsa caller shares one AgentMail account, so this reaches inboxes other callers created; the inbox-scoped twin `get_agentmail_inbox_threads_search` is the one to use when a single inbox is meant.
## Example
```bash REST theme={null}
curl -X GET "https://api.aisa.one/apis/v1/agentmail/threads/search" \
-H "Authorization: Bearer YOUR_API_KEY"
```
```jsonc MCP theme={null}
// Copy this whole block into Claude Code, Codex, Cursor or any coding agent.
// It carries everything needed to connect, authorize and run this example —
// no key to paste, one click of Allow in the browser.
{
"operation_id": "get_agentmail_threads_search",
"arguments": {},
"max_price_usd": 0.05
}
// ── for the agent ─────────────────────────────────────────────────────────
// Register the AIsa MCP server, then call its `use` tool with the JSON above.
// name aisa
// endpoint https://mcp.aisa.one/mcp
// transport streamable-http
// auth OAuth. The server publishes RFC 9728 metadata, so open a
// browser and the user clicks Allow once — nothing to paste.
// If AISA_API_KEY is set, send it as a bearer header instead.
// Use your own MCP mechanism, not a hand-edited config file:
// Codex codex mcp add aisa --url https://mcp.aisa.one/mcp
// Claude Code claude mcp add --transport http -s user aisa https://mcp.aisa.one/mcp
// Cursor / VS Code a "url" entry for https://mcp.aisa.one/mcp in the MCP config
// The server lists five tools over https://mcp.aisa.one/servers worth of APIs:
// search, get_details, use, batch_use, list_categories. search and
// get_details are free; use is billed per call and max_price_usd refuses
// anything above the cap before spending. This operation's full contract —
// every argument, the response shape, the price and the pitfalls — is at
// https://aisa.one/docs/api-reference/agentmail/get_agentmail-threads-search.md
// Then run the call and show me the result.
```
**First time?** Point any MCP client at `https://mcp.aisa.one/mcp` — Claude
Code, Codex, Cursor, VS Code and the rest. Authorization is OAuth: the client
opens a browser, you click Allow once, and there is no key to paste. The
commands per client, and what each call costs, are on
[aisa.one/mcp](https://aisa.one/mcp#connect).
[Set this endpoint up in your agent →](https://aisa.one/mcp?from=/api-reference/agentmail/get_agentmail-threads-search)
## OpenAPI
````yaml openapi/agentmail.json GET /agentmail/threads/search
openapi: 3.1.0
info:
title: AgentMail API
version: 1.0.0
description: >-
AgentMail email API endpoints exposed through the AIsa unified gateway.
Adapted from the upstream docs.agentmail.to OpenAPI spec.
servers:
- url: https://api.aisa.one/apis/v1
security:
- Bearer: []
paths:
/agentmail/threads/search:
get:
tags:
- AgentMail
summary: Search All Threads
description: >-
Full-text search over threads in **every inbox in the account**. Returns
`count`, `limit`, `next_page_token` and `threads`; page with
`next_page_token`. Same fields as `get_agentmail_threads`, which is the
one to use for everything in date order. This is the organization-wide
view spanning every inbox in the account. Every AIsa caller shares one
AgentMail account, so this reaches inboxes other callers created; the
inbox-scoped twin `get_agentmail_inbox_threads_search` is the one to use
when a single inbox is meant.
operationId: get_agentmail_threads_search
parameters:
- name: q
in: query
required: true
schema:
$ref: '#/components/schemas/type__Query'
- name: limit
in: query
required: false
schema:
$ref: '#/components/schemas/type__Limit'
- name: page_token
in: query
required: false
schema:
$ref: '#/components/schemas/type__PageToken'
- name: before
in: query
required: false
schema:
$ref: '#/components/schemas/type__Before'
- name: after
in: query
required: false
schema:
$ref: '#/components/schemas/type__After'
- name: Authorization
in: header
description: Bearer authentication
required: true
schema:
type: string
responses:
'200':
description: Response with status 200
content:
application/json:
schema:
$ref: '#/components/schemas/type_threads_SearchThreadsResponse'
'400':
description: Error response with status 400
content:
application/json:
schema:
$ref: '#/components/schemas/type__ValidationErrorResponse'
'404':
description: Error response with status 404
content:
application/json:
schema:
$ref: '#/components/schemas/type__ErrorResponse'
security:
- Bearer: []
components:
schemas:
type__Query:
type: string
description: |-
Full-text search query. Matched against the sender, recipients, and
subject (substring) and the message body (tokenized full text).
title: Query
type__Limit:
type: integer
description: Limit of number of items returned.
title: Limit
type__PageToken:
type: string
description: Page token for pagination.
title: PageToken
type__Before:
type: string
format: date-time
description: Timestamp before which to filter by.
title: Before
type__After:
type: string
format: date-time
description: Timestamp after which to filter by.
title: After
type_threads_SearchThreadsResponse:
type: object
properties:
count:
$ref: '#/components/schemas/type__Count'
limit:
$ref: '#/components/schemas/type__Limit'
next_page_token:
$ref: '#/components/schemas/type__PageToken'
threads:
type: array
items:
$ref: '#/components/schemas/type_threads_SearchThreadItem'
description: Ordered by relevance, best match first.
required:
- count
- threads
title: SearchThreadsResponse
type__ValidationErrorResponse:
type: object
properties:
name:
$ref: '#/components/schemas/type__ErrorName'
errors:
description: Validation errors.
required:
- name
- errors
title: ValidationErrorResponse
type__ErrorResponse:
type: object
properties:
name:
$ref: '#/components/schemas/type__ErrorName'
message:
$ref: '#/components/schemas/type__ErrorMessage'
required:
- name
- message
title: ErrorResponse
type__Count:
type: integer
description: Number of items returned.
title: Count
type_threads_SearchThreadItem:
type: object
properties:
inbox_id:
$ref: '#/components/schemas/type_inboxes_InboxId'
thread_id:
$ref: '#/components/schemas/type_threads_ThreadId'
labels:
$ref: '#/components/schemas/type_threads_ThreadLabels'
timestamp:
$ref: '#/components/schemas/type_threads_ThreadTimestamp'
received_timestamp:
$ref: '#/components/schemas/type_threads_ThreadReceivedTimestamp'
sent_timestamp:
$ref: '#/components/schemas/type_threads_ThreadSentTimestamp'
senders:
$ref: '#/components/schemas/type_threads_ThreadSenders'
recipients:
$ref: '#/components/schemas/type_threads_ThreadRecipients'
subject:
$ref: '#/components/schemas/type_threads_ThreadSubject'
preview:
$ref: '#/components/schemas/type_threads_ThreadPreview'
attachments:
$ref: '#/components/schemas/type_threads_ThreadAttachments'
last_message_id:
$ref: '#/components/schemas/type_threads_ThreadLastMessageId'
message_count:
$ref: '#/components/schemas/type_threads_ThreadMessageCount'
size:
$ref: '#/components/schemas/type_threads_ThreadSize'
updated_at:
$ref: '#/components/schemas/type_threads_ThreadUpdatedAt'
created_at:
$ref: '#/components/schemas/type_threads_ThreadCreatedAt'
highlights:
$ref: '#/components/schemas/type_threads_SearchThreadHighlights'
description: >-
Matched fragments per field. Present only when the query matched an
indexed field.
required:
- inbox_id
- thread_id
- labels
- timestamp
- senders
- recipients
- last_message_id
- message_count
- size
- updated_at
- created_at
title: SearchThreadItem
type__ErrorName:
type: string
description: Name of error.
title: ErrorName
type__ErrorMessage:
type: string
description: Error message.
title: ErrorMessage
type_inboxes_InboxId:
type: string
description: The ID of the inbox.
title: InboxId
type_threads_ThreadId:
type: string
description: ID of thread.
title: ThreadId
type_threads_ThreadLabels:
type: array
items:
type: string
description: Labels of thread.
title: ThreadLabels
type_threads_ThreadTimestamp:
type: string
format: date-time
description: Timestamp of last sent or received message.
title: ThreadTimestamp
type_threads_ThreadReceivedTimestamp:
type: string
format: date-time
description: Timestamp of last received message.
title: ThreadReceivedTimestamp
type_threads_ThreadSentTimestamp:
type: string
format: date-time
description: Timestamp of last sent message.
title: ThreadSentTimestamp
type_threads_ThreadSenders:
type: array
items:
type: string
description: >-
Senders in thread. In format `username@domain.com` or `Display Name
`.
title: ThreadSenders
type_threads_ThreadRecipients:
type: array
items:
type: string
description: >-
Recipients in thread. In format `username@domain.com` or `Display Name
`.
title: ThreadRecipients
type_threads_ThreadSubject:
type: string
description: Subject of thread.
title: ThreadSubject
type_threads_ThreadPreview:
type: string
description: Text preview of last message in thread.
title: ThreadPreview
type_threads_ThreadAttachments:
type: array
items:
$ref: '#/components/schemas/type_attachments_Attachment'
description: Attachments in thread.
title: ThreadAttachments
type_threads_ThreadLastMessageId:
type: string
description: ID of last message in thread.
title: ThreadLastMessageId
type_threads_ThreadMessageCount:
type: integer
description: Number of messages in thread.
title: ThreadMessageCount
type_threads_ThreadSize:
type: integer
description: Size of thread in bytes.
title: ThreadSize
type_threads_ThreadUpdatedAt:
type: string
format: date-time
description: Time at which thread was last updated.
title: ThreadUpdatedAt
type_threads_ThreadCreatedAt:
type: string
format: date-time
description: Time at which thread was created.
title: ThreadCreatedAt
type_threads_SearchThreadHighlights:
type: object
properties:
from:
type: array
items:
type: string
description: Matched fragments from a sender address in the thread.
recipients:
type: array
items:
type: string
description: >-
Matched fragments from a recipient address in the thread (to, cc, or
bcc).
subject:
type: array
items:
type: string
description: Matched fragments from the subject.
text:
type: array
items:
type: string
description: Matched fragments from a message body in the thread.
description: >-
Matched fragments per field on a thread search result, with matched
terms
wrapped in `**`. A field key is present only when the query matched that
field, so the present keys also tell you which fields produced the hit.
title: SearchThreadHighlights
type_attachments_Attachment:
type: object
properties:
attachment_id:
$ref: '#/components/schemas/type_attachments_AttachmentId'
filename:
$ref: '#/components/schemas/type_attachments_AttachmentFilename'
size:
$ref: '#/components/schemas/type_attachments_AttachmentSize'
content_type:
$ref: '#/components/schemas/type_attachments_AttachmentContentType'
content_disposition:
$ref: '#/components/schemas/type_attachments_AttachmentContentDisposition'
content_id:
$ref: '#/components/schemas/type_attachments_AttachmentContentId'
required:
- attachment_id
- size
title: Attachment
type_attachments_AttachmentId:
type: string
description: ID of attachment.
title: AttachmentId
type_attachments_AttachmentFilename:
type: string
description: Filename of attachment.
title: AttachmentFilename
type_attachments_AttachmentSize:
type: integer
description: Size of attachment in bytes.
title: AttachmentSize
type_attachments_AttachmentContentType:
type: string
description: Content type of attachment.
title: AttachmentContentType
type_attachments_AttachmentContentDisposition:
type: string
enum:
- inline
- attachment
description: Content disposition of attachment.
title: AttachmentContentDisposition
type_attachments_AttachmentContentId:
type: string
description: Content ID of attachment.
title: AttachmentContentId
securitySchemes:
Bearer:
type: http
scheme: bearer
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.