> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gork.email/llms.txt
> Use this file to discover all available pages before exploring further.

# Search Messages

> Search a mailbox by free text and filters — subject, body, sender and recipients.

Mail accumulates fast when an agent runs on its own. Instead of pulling the
whole inbox and filtering client-side, ask for exactly what you need: the
invoice, the reset link, everything a customer sent this week.

Search is case-insensitive and matches across the **subject**, the **body**,
the **sender** (address and display name) and the **recipients**. Results are
newest first.

### Query parameters

<ParamField query="q" type="string">
  Free-text terms. Up to 200 characters. `%` and `_` are treated literally, so
  searching for `50%` does not match everything.
</ParamField>

<ParamField query="inboxId" type="string">
  Restrict the search to one inbox. Inbox-bound keys are always restricted to
  their own inbox regardless of this value.
</ParamField>

<ParamField query="direction" type="string">
  `inbound` for received mail, `outbound` for sent mail.
</ParamField>

<ParamField query="from" type="string">
  Substring match against the sender address (`from=acme.com`).
</ParamField>

<ParamField query="since" type="string">
  ISO date or timestamp lower bound, e.g. `2026-09-01`.
</ParamField>

<ParamField query="until" type="string">
  ISO date or timestamp upper bound.
</ParamField>

<ParamField query="limit" type="number" default="50">
  Maximum results, 1–100.
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  # Everything about invoice 1042
  curl -s "https://api.gork.email/v1/messages?q=invoice%201042" \
    -H "Authorization: Bearer gork_live_YOUR_API_KEY"

  # Mail from a domain, since a date, received only
  curl -s "https://api.gork.email/v1/messages?from=acme.com&since=2026-09-01&direction=inbound" \
    -H "Authorization: Bearer gork_live_YOUR_API_KEY"
  ```

  ```typescript TypeScript theme={null}
  import { GorkClient } from "@gork/sdk"

  const client = new GorkClient({ apiKey: process.env.GORK_API_KEY })

  const hits = await client.messages.search("invoice 1042")
  const recent = await client.messages.list({ from: "acme.com", since: "2026-09-01" })
  ```
</RequestExample>

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "data": [
      {
        "id": "msg_90e38dfb4a2c",
        "direction": "inbound",
        "fromAddress": "billing@acme.com",
        "toAddresses": ["agent@yourdomain.com"],
        "subject": "Invoice 1042",
        "status": "received",
        "createdAt": "2026-09-11T08:00:00.000Z"
      }
    ]
  }
  ```
</ResponseExample>

## From an agent (MCP)

The `gork_search_emails` tool exposes the same query with `direction`, `from`,
`since` and `until` filters, and returns a compact list of hits.