Search

GET /v0/inboxes/{inbox}/messages/search searches every message of one inbox on the server. It is not a filter over a page you already loaded: a query reaches the whole inbox, including mail your client has never seen.

What comes back

The criteria apply to the message, not to the thread. A message that matches brings its thread_id with it, and the answer is a list of messages, newest first, paginated with limit (1 to 100, default 20) and cursor (from next_cursor). Group the hits by thread_id to show conversations; every hit also carries snippet, an excerpt around the match.

A negation excludes the message, never the thread: -from:noreply hides that message, and the rest of its conversation stays findable through the other messages. Criteria of different fields are ANDed. The values of one repeated parameter (from, to, subject, label) are ORed.

The query language

• Free text matches message text, subject and sender, ignoring case and accents: fattura finds Fattura and perché is found by perche.
• "fattura marzo" in quotes is an exact phrase: adjacent words in that order. It does not match marzo fattura.
• A leading minus excludes: -from:noreply@example.com, -subject:newsletter, -label:archived.
• from:, to:, subject: and label: take a value, and can be negated with a minus.
• is: accepts unread, read or flagged. read means "no unread label", because the unread label is the only read state a message carries.
• has_attachment:true keeps only messages with files; has_attachment:false only those without.
• after: and before: take an RFC 3339 timestamp (or pass after= and before= as parameters); both are inclusive.

curl -s -G https://api.mueslimail.com/v0/inboxes/{inbox}/messages/search \
  -H "Authorization: Bearer $MAI_API_KEY" \
  --data-urlencode 'q="fattura marzo" -from:noreply' \
  --data-urlencode 'has_attachment=true' \
  --data-urlencode 'after=2026-01-01T00:00:00Z' \
  --data-urlencode 'limit=50'

The economical permission

message_read returns the mail, with a snippet for every hit. message_metadata is the narrower permission: a key holding only that one matches the headers (subject and sender) and receives no body, no preview and no snippet. It is what an economical sync or a routing agent should hold: it can find a message and route it without reading it. Asking for a body word returns nothing for such a key, so the permission cannot be used to probe text it may not read.

Pagination

The cursor is a keyset over (created_at, id) descending, so a message that arrives while you read page two neither shifts nor repeats a row of page one: new mail is newer than the cursor, which is the one direction the next page does not look.

Endpoints