> ## 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 Inbox Threads

> Search AgentMail threads in a specific inbox using a full-text query.



## OpenAPI

````yaml openapi/agentmail.json GET /agentmail/inboxes/{inbox_id}/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/inboxes/{inbox_id}/threads/search:
    get:
      tags:
        - AgentMail
      summary: Search Threads
      description: |-
        Full-text search across threads in the inbox, ranked by relevance. The
        query is matched against senders, recipients, and subject (substring)
        and the message body (tokenized full text). Spam, trash, blocked, and
        unauthenticated threads are always excluded. `limit` cannot exceed 100.
      operationId: get_agentmail_inboxes_inbox_id_threads_search
      parameters:
        - name: inbox_id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/type_inboxes_InboxId'
        - 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_inboxes_InboxId:
      type: string
      description: The ID of the inbox.
      title: InboxId
    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_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
        <username@domain.com>`.
      title: ThreadSenders
    type_threads_ThreadRecipients:
      type: array
      items:
        type: string
      description: >-
        Recipients in thread. In format `username@domain.com` or `Display Name
        <username@domain.com>`.
      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

````