import { createClient } from "@mailsai/sdk";

const client = createClient(); // reads MAILS_API_KEY

const result = await client.search({ q: "invoice" });
console.log(result);

from mailsai import create_client

client = create_client()  # reads MAILS_API_KEY

result = client.search(q="invoice")
print(result)

curl 'https://api.mails.ai/v1/search?q=invoice' \
  -H "Authorization: Bearer $MAILS_API_KEY"

mails search "refund"
mails search invoice --from billing@acme.com \
  --has-attachment --json

{
  "name": "mails_search_mail",
  "arguments": { "q": "invoice" }
}

{
  "data": [
    {
      "type": "received",
      "id": "rcv_01JZX8K3M9Q4P7VN2YB6RTDC0E",
      "thread_id": "thrd_01JZX8K3M9Q4P7VN2YB6RTDC0E",
      "agent_id": "agt_01JZX8K3M9Q4P7VN2YB6RTDC0E",
      "subject": "<subject>",
      "from": {
        "address": "<address>",
        "name": "<name>"
      },
      "to": ["<to>"],
      "date": "2026-10-04T12:00:00.000Z",
      "has_attachment": false,
      "folder": "inbox",
      "labels": ["<labels>"],
      "snippet": "<snippet>"
    }
  ],
  "has_more": false,
  "next_cursor": "<next_cursor>"
}

200  A page of hits.
400  Invalid request — malformed JSON or a field failed
     validation. Also feature_not_enabled when this
     server has a feature switched off (custom domains
     before they are available).
401  Missing or invalid API key.
403  The API key lacks the required scope
     (insufficient_scope), or the token belongs to an
     app connected by sign-in and this operation is
     closed to connected apps
     (connected_app_not_allowed).
409  Conflict — duplicate resource, an in-progress
     idempotent request, a draft or scheduled message
     that started sending while it was being changed, or
     a thread deleted for good while one of its messages
     is being sent (duplicate_resource); or an agent
     name more than one agent has (agent_name_conflict:
     use the agent's id); or a status change on an
     archived agent, since archiving cannot be undone
     (agent_archived).
429  Rate or quota limit exceeded. The body's resets_at
     and retry_after_seconds say when the request can
     succeed. A Retry-After header is sent only when
     that is 60 seconds or less; a longer wait (an
     hourly, daily or monthly cap) sends none, so retry
     at resets_at or raise the limit instead of
     sleeping.
500  Internal server error.

Search mail

Full-text search over received and sent mail (subject, body text and addresses), newest first.

GET/v1/searchscope · read

import { createClient } from "@mailsai/sdk";

const client = createClient(); // reads MAILS_API_KEY

const result = await client.search({ q: "invoice" });
console.log(result);

from mailsai import create_client

client = create_client()  # reads MAILS_API_KEY

result = client.search(q="invoice")
print(result)

curl 'https://api.mails.ai/v1/search?q=invoice' \
  -H "Authorization: Bearer $MAILS_API_KEY"

mails search "refund"
mails search invoice --from billing@acme.com \
  --has-attachment --json

{
  "name": "mails_search_mail",
  "arguments": { "q": "invoice" }
}

{
  "data": [
    {
      "type": "received",
      "id": "rcv_01JZX8K3M9Q4P7VN2YB6RTDC0E",
      "thread_id": "thrd_01JZX8K3M9Q4P7VN2YB6RTDC0E",
      "agent_id": "agt_01JZX8K3M9Q4P7VN2YB6RTDC0E",
      "subject": "<subject>",
      "from": {
        "address": "<address>",
        "name": "<name>"
      },
      "to": ["<to>"],
      "date": "2026-10-04T12:00:00.000Z",
      "has_attachment": false,
      "folder": "inbox",
      "labels": ["<labels>"],
      "snippet": "<snippet>"
    }
  ],
  "has_more": false,
  "next_cursor": "<next_cursor>"
}

200  A page of hits.
400  Invalid request — malformed JSON or a field failed
     validation. Also feature_not_enabled when this
     server has a feature switched off (custom domains
     before they are available).
401  Missing or invalid API key.
403  The API key lacks the required scope
     (insufficient_scope), or the token belongs to an
     app connected by sign-in and this operation is
     closed to connected apps
     (connected_app_not_allowed).
409  Conflict — duplicate resource, an in-progress
     idempotent request, a draft or scheduled message
     that started sending while it was being changed, or
     a thread deleted for good while one of its messages
     is being sent (duplicate_resource); or an agent
     name more than one agent has (agent_name_conflict:
     use the agent's id); or a status change on an
     archived agent, since archiving cannot be undone
     (agent_archived).
429  Rate or quota limit exceeded. The body's resets_at
     and retry_after_seconds say when the request can
     succeed. A Retry-After header is sent only when
     that is 60 seconds or less; a longer wait (an
     hourly, daily or monthly cap) sends none, so retry
     at resets_at or raise the limit instead of
     sleeping.
500  Internal server error.

Query Parameters

qstring

Full-text search: every word must appear in the subject, body or addresses, as a whole word or, from three letters up, the start of one (inv finds invoice). At most 16 different words (more is a 400).

agent_idstring

Filter by agent id or name. A key tied to one agent always reads that agent's mail, and naming another agent is a 403.

fromstring

The sender's address contains this text (the display name, which the sender chooses, is not matched).

tostring

A recipient address contains this text.

afterstring

Only mail at or after this time (ISO 8601, or YYYY-MM-DD).

beforestring

Only mail before this time (ISO 8601, or YYYY-MM-DD).

has_attachmentboolean

true for mail with a file attachment, false for mail without.

folderstring

Which folder's mail to return, or all for every folder. Without it: every folder except trash.

One of: inbox, archive, spam, trash, sent, all

labelstring

Only mail in threads carrying this label (a name, or a label id lbl_…).

typestring

Only received or only sent mail.

One of: received, sent

limitinteger

Page size (1–100).

Default: 25

cursorstring

Opaque cursor from a previous page's next_cursor.

Each hit says whether it was received or sent and carries a snippet around the match. Never leaves the workspace; a key tied to one agent searches that agent's mail; a test key searches test mail only and a live key live mail only. A search that runs past 5 seconds is stopped (400, narrow it), and a workspace may search 120 times a minute (429 with Retry-After past that).

Response

dataobject[]

The items on this page, at most limit of them.

Show propertiesHide properties

typestring

received for a message an agent received, sent for one it sent; it says which kind of id id is.

One of: received, sent

idstring

The message id (rcv_… or msg_…).

thread_idstring | null

The thread (thrd_…) the message is in. Null for a message in no thread.

agent_idstring

Id (agt_…) of the agent that received or sent the message.

subjectstring | null

The message's subject. Null when it has none.

fromobject

Who the message is from: the sender for received mail, the agent itself for sent mail.

Show propertiesHide properties

addressstring

The sender's address for received mail, as on the received message's from.address; the sending agent's address for sent mail.

namestring | null

The sender's display name on received mail, null when there is none. Always null on sent mail.

tostring[]

For received mail, the one agent address it was delivered to. For sent mail, its to recipients; cc and bcc are not listed.

datestring

Received time, or sent time for sent mail.

has_attachmentboolean

For received mail, true when it carries at least one file attachment (images embedded in the HTML do not count); for sent mail, true when it was sent with any.

folderstring | null

The folder of the message's thread. A message in no thread counts as inbox; null only when its thread cannot be found.

One of: inbox, archive, spam, trash, sent

labelsstring[]

The label names on the message's thread. Empty when the thread has none or the message is in no thread.

snippetstring

Plain text from the message's body around the match (the start of the body when the match is only in the subject or an address, or when q is absent).

has_moreboolean

True when more items follow this page: pass next_cursor as cursor to get them.

next_cursorstring

Pass as cursor to fetch the next page. Absent on the last page.

Was this page helpful?