cherami.
Guides

Find mail

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

Read as Markdown ↗

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

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, the filters are ordinary listing parameters:

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, dictionary keys keep the HTTP filter names, including from:

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

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 and tell us what you're trying to find.

Combine filters

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

ParameterMeaning
queryWords and double-quoted phrases in the subject or body.
fromExact address in the visible From, ignoring case; not the SMTP envelope sender.
recipientExact address in To, Cc or Bcc, ignoring case. Received mail rarely shows Bcc.
subjectText the subject contains, ignoring case.
afterReceived or sent at or after this time.
beforeReceived or sent before this time.
labels_allHas every listed label.
labels_anyHas at least one listed label.
labels_noneHas 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, and the parameter reference 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

orderResult order
newestNewest first; the default.
oldestOldest first.
relevanceStrongest 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

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, which returns the whole conversation, unfiltered.

Received-message reference · Sent-message reference · Conversation reference

On this page