# Find mail

Search words and phrases, combine message filters, and find matching conversations.

Source: https://cherami.to/docs/guides/search



Set `INBOX_ID` and `CHERAMI_API_KEY`, then add `query` and filters to the received, sent or conversation listing:

```bash
curl --get "https://cherami.to/v1/inboxes/$INBOX_ID/messages" \
  -H "Authorization: Bearer $CHERAMI_API_KEY" \
  --data-urlencode 'query="project invoice"' \
  --data-urlencode 'from=alice@example.com' \
  --data-urlencode 'labels_all=needs-attention' \
  --data-urlencode 'order=relevance'
```

With MCP, use `list_messages`, `list_sent` or `list_threads` with the same named filters. `count_messages` (`GET /v1/inboxes/INBOX_ID/messages/count`) counts received mail with the same filters, without order or pagination.

With the [TypeScript SDK](https://cherami.to/docs/typescript), the filters are ordinary listing parameters:

```ts
for await (const message of client.iterate("listMessages", {
  inbox_id: inboxId,
  query: '"project invoice"',
  from: "alice@example.com",
  labels_all: ["needs-attention"],
  order: "relevance",
}, { maxPages: 5 })) {
  console.log(message.id);
}
```

Use `client.pages` instead when you need each page's `next_cursor` to resume later.

With the [Python SDK](https://cherami.to/docs/python), dictionary keys keep the HTTP filter names, including `from`:

```python
for message in client.iterate("list_messages", {
    "inbox_id": inbox_id,
    "query": '"project invoice"',
    "from": "alice@example.com",
    "labels_all": ["needs-attention"],
    "order": "relevance",
}, max_pages=5):
    print(message["id"])
```

With `AsyncCherami`, use `async for`.

## Search words and phrases [#search-words-and-phrases]

`query` searches subjects and bodies, quoted history included, but not attachments or other headers.

Every term must appear in the same message, though they can be in different parts of its subject or body. Double quotes require consecutive words in the subject or the body. For example, `invoice "repair workshop"` requires both `invoice` and the phrase `repair workshop`.

Matching ignores case and Latin diacritics. It matches whole words, not parts of words or word stems. Punctuation separates words; `OR`, `NOT` and wildcards have no special meaning. To match part of a subject, use `subject` instead.

Need semantic search? Email [hello@cherami.to](mailto:hello@cherami.to) and tell us what you're trying to find.

## Combine filters [#combine-filters]

Every condition you supply must match. Leave one out to leave it unrestricted.

| Parameter     | Meaning                                                                         |
| ------------- | ------------------------------------------------------------------------------- |
| `query`       | Words and double-quoted phrases in the subject or body.                         |
| `from`        | Exact address in the visible From, ignoring case; not the SMTP envelope sender. |
| `recipient`   | Exact address in To, Cc or Bcc, ignoring case. Received mail rarely shows Bcc.  |
| `subject`     | Text the subject contains, ignoring case.                                       |
| `after`       | Received or sent at or after this time.                                         |
| `before`      | Received or sent before this time.                                              |
| `labels_all`  | Has every listed label.                                                         |
| `labels_any`  | Has at least one listed label.                                                  |
| `labels_none` | Has none of the listed labels.                                                  |

Write times as `YYYY-MM-DDTHH:mm:ss` followed by `Z` or an offset such as `+02:00`, with up to three optional fractional digits: `2026-10-01T00:00:00.123Z`. A date without a time, or a time without a timezone, is refused. URL-encode offsets in HTTP so `+` isn't read as a space. Times are when we received or sent the message, never the sender's Date header. For a local calendar day, use its start as `after` and the next day's start as `before`.

In HTTP, repeat a label parameter for each label; in MCP and the SDKs, pass an array. Labels match case-sensitively. See [labels](https://cherami.to/docs/guides/labels), and the [parameter reference](https://cherami.to/docs/api/messages/list-messages#parameters) for limits.

Mail that failed processing doesn't match `query`, `from`, `recipient` or `subject`; date and label filters still find it. Sent results include rejected and unknown attempts.

## Choose an order [#choose-an-order]

| `order`     | Result order                                                                             |
| ----------- | ---------------------------------------------------------------------------------------- |
| `newest`    | Newest first; the default.                                                               |
| `oldest`    | Oldest first.                                                                            |
| `relevance` | Strongest keyword matches first, with subject matches weighted higher; requires `query`. |

With `newest` or `oldest`, conversations sort by their latest activity, not by when their matching messages arrived.

Follow `next_cursor` with the same filters and order; start without a cursor for a fresh view.

## Find a conversation [#find-a-conversation]

`list_threads` and `GET /v1/inboxes/INBOX_ID/threads` return a conversation when **one message in it satisfies every condition**. A sender match on one message and a keyword match on another don't qualify it. Label exclusions apply to that matching message, not to the rest of the conversation.

Filtered results add `matching_message_ids` (up to 100, newest first) and `matching_message_count`. The conversation's counts, subject and activity still describe all of it. Read it with `get_thread` or the [thread detail endpoint](https://cherami.to/docs/api/threads/get-thread), which returns the whole conversation, unfiltered.

[Received-message reference](https://cherami.to/docs/api/messages) · [Sent-message reference](https://cherami.to/docs/api/sending) · [Conversation reference](https://cherami.to/docs/api/threads)
