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

# search_emails

> Search the authenticated user's mailbox — free-text search combined with category, sender, date-range, and mailbox filters.

Searches the mailbox and returns a compact, newest-first hit list without message bodies. Combine free text with any of the structured filters; **at least one filter is required**. Fetch a full message with [`get_email`](/reference/mcp/get-email).

## Parameters

<ParamField body="query" type="string">
  Free-text full-text search over subject and body. 1–500 characters.
</ParamField>

<ParamField body="after" type="string">
  Only messages received on or after this UTC ISO 8601 timestamp, e.g. `2026-04-01T00:00:00Z`.
</ParamField>

<ParamField body="before" type="string">
  Only messages received strictly before this UTC ISO 8601 timestamp, e.g. `2026-07-01T00:00:00Z`.
</ParamField>

<ParamField body="from" type="string">
  Substring match on the sender's name or address. 1–200 characters.
</ParamField>

<ParamField body="keywords" type="string[]">
  Category labels to filter by; multiple values combine with OR. At least one value when present. Valid values:

  | Value          | Meaning                                                                                     |
  | -------------- | ------------------------------------------------------------------------------------------- |
  | `direct`       | Personal emails from individuals and direct conversations                                   |
  | `receipt`      | Order confirmations, shipping updates, delivery notifications, purchase receipts            |
  | `newsletter`   | Regular updates, news digests, curated content                                              |
  | `notification` | Security alerts, terms updates, service notifications                                       |
  | `promotional`  | Marketing emails, sales pitches, discount offers                                            |
  | `todo`         | Messages flagged as an action item — see [Email intelligence](/concepts/email-intelligence) |
</ParamField>

<ParamField body="mailbox" type="string">
  Restrict to a named mailbox/folder, e.g. `Inbox`.
</ParamField>

<ParamField body="limit" type="integer" default="20">
  Maximum results, 1–100.
</ParamField>

## Example

```json Call theme={null}
{
  "query": "invoice",
  "keywords": ["receipt"],
  "after": "2026-06-01T00:00:00Z",
  "limit": 10
}
```

```text Result theme={null}
2 message(s) matched:

1. Your invoice for June
   id: Mabc123
   from: Acme Billing <billing@acme.example>
   date: 2026-07-05T08:12:00Z
   tags: receipt

2. Invoice #4021
   id: Mab9f01
   from: Hosting Co <billing@hosting.example>
   date: 2026-06-14T07:30:00Z
   tags: receipt
```

Messages with no category tags omit the `tags:` line. An empty result returns `No messages matched.`

## Errors

* `Provide at least one filter: query, after, before, from, keywords, or mailbox.` — the call had no filter.
* `Mailbox not found: <name>` — the `mailbox` value didn't match a folder.