> ## 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 Messages

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



## OpenAPI

````yaml openapi/agentmail.json GET /agentmail/inboxes/{inbox_id}/messages/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}/messages/search:
    get:
      tags:
        - AgentMail
      summary: Search Messages
      description: |-
        Full-text search across messages in the inbox, ranked by relevance. The
        query is matched against the sender, recipients, and subject (substring)
        and the message body (tokenized full text). Spam, trash, blocked, and
        unauthenticated messages are always excluded. `limit` cannot exceed 100.
      operationId: get_agentmail_inboxes_inbox_id_messages_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_messages_SearchMessagesResponse'
        '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_messages_SearchMessagesResponse:
      type: object
      properties:
        count:
          $ref: '#/components/schemas/type__Count'
        limit:
          $ref: '#/components/schemas/type__Limit'
        next_page_token:
          $ref: '#/components/schemas/type__PageToken'
        messages:
          type: array
          items:
            $ref: '#/components/schemas/type_messages_SearchMessageItem'
          description: Ordered by relevance, best match first.
      required:
        - count
        - messages
      title: SearchMessagesResponse
    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_messages_SearchMessageItem:
      type: object
      properties:
        inbox_id:
          $ref: '#/components/schemas/type_inboxes_InboxId'
        thread_id:
          $ref: '#/components/schemas/type_threads_ThreadId'
        message_id:
          $ref: '#/components/schemas/type_messages_MessageId'
        labels:
          $ref: '#/components/schemas/type_messages_MessageLabels'
        timestamp:
          $ref: '#/components/schemas/type_messages_MessageTimestamp'
        from:
          $ref: '#/components/schemas/type_messages_MessageFrom'
        to:
          $ref: '#/components/schemas/type_messages_MessageTo'
        cc:
          $ref: '#/components/schemas/type_messages_MessageCc'
        bcc:
          $ref: '#/components/schemas/type_messages_MessageBcc'
        subject:
          $ref: '#/components/schemas/type_messages_MessageSubject'
        preview:
          $ref: '#/components/schemas/type_messages_MessagePreview'
        attachments:
          $ref: '#/components/schemas/type_messages_MessageAttachments'
        in_reply_to:
          $ref: '#/components/schemas/type_messages_MessageInReplyTo'
        references:
          $ref: '#/components/schemas/type_messages_MessageReferences'
        headers:
          $ref: '#/components/schemas/type_messages_MessageHeaders'
        size:
          $ref: '#/components/schemas/type_messages_MessageSize'
        updated_at:
          $ref: '#/components/schemas/type_messages_MessageUpdatedAt'
        created_at:
          $ref: '#/components/schemas/type_messages_MessageCreatedAt'
        highlights:
          $ref: '#/components/schemas/type_messages_SearchMessageHighlights'
          description: >-
            Matched fragments per field. Present only when the query matched an
            indexed field.
      required:
        - inbox_id
        - thread_id
        - message_id
        - labels
        - timestamp
        - from
        - to
        - size
        - updated_at
        - created_at
      title: SearchMessageItem
    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_messages_MessageId:
      type: string
      description: ID of message.
      title: MessageId
    type_messages_MessageLabels:
      type: array
      items:
        type: string
      description: Labels of message.
      title: MessageLabels
    type_messages_MessageTimestamp:
      type: string
      format: date-time
      description: Time at which message was sent or drafted.
      title: MessageTimestamp
    type_messages_MessageFrom:
      type: string
      description: >-
        Address of sender. In format `username@domain.com` or `Display Name
        <username@domain.com>`.
      title: MessageFrom
    type_messages_MessageTo:
      type: array
      items:
        type: string
      description: >-
        Addresses of recipients. In format `username@domain.com` or `Display
        Name <username@domain.com>`.
      title: MessageTo
    type_messages_MessageCc:
      type: array
      items:
        type: string
      description: >-
        Addresses of CC recipients. In format `username@domain.com` or `Display
        Name <username@domain.com>`.
      title: MessageCc
    type_messages_MessageBcc:
      type: array
      items:
        type: string
      description: >-
        Addresses of BCC recipients. In format `username@domain.com` or `Display
        Name <username@domain.com>`.
      title: MessageBcc
    type_messages_MessageSubject:
      type: string
      description: Subject of message.
      title: MessageSubject
    type_messages_MessagePreview:
      type: string
      description: Text preview of message.
      title: MessagePreview
    type_messages_MessageAttachments:
      type: array
      items:
        $ref: '#/components/schemas/type_attachments_Attachment'
      description: Attachments in message.
      title: MessageAttachments
    type_messages_MessageInReplyTo:
      type: string
      description: ID of message being replied to.
      title: MessageInReplyTo
    type_messages_MessageReferences:
      type: array
      items:
        type: string
      description: IDs of previous messages in thread.
      title: MessageReferences
    type_messages_MessageHeaders:
      type: object
      additionalProperties:
        type: string
      description: Headers in message.
      title: MessageHeaders
    type_messages_MessageSize:
      type: integer
      description: Size of message in bytes.
      title: MessageSize
    type_messages_MessageUpdatedAt:
      type: string
      format: date-time
      description: Time at which message was last updated.
      title: MessageUpdatedAt
    type_messages_MessageCreatedAt:
      type: string
      format: date-time
      description: Time at which message was created.
      title: MessageCreatedAt
    type_messages_SearchMessageHighlights:
      type: object
      properties:
        from:
          type: array
          items:
            type: string
          description: Matched fragments from the sender address.
        recipients:
          type: array
          items:
            type: string
          description: Matched fragments from the recipient addresses (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 the message body.
      description: >-
        Matched fragments per field on a message 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: SearchMessageHighlights
    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

````