Module mailsearch 

Searching the mail by conditions (docs/client.md, “Searching”).

The conditions are the mail filters’ own (rules::Condition: a field, a test, a value; all of them or any, rules::Join): a search can become a filter as it is, and what a filter would take, a search finds. The search adds four fields of its own to them (rules::Field::SEARCH): anywhere, the address, the folder, a mark (read, flagged, answered).

Here:

• how a stored message is matched (Stored): its headers read first, alone, and the whole message only when a condition needs it (its text, its attachments); a message seen on its server only (Found) is matched on its headers and its parts (BODYSTRUCTURE), its text being the server’s to match;
• which folders a search reaches (Search::reaches): the junk and the trash only when a folder condition names them;
• the same search as IMAP’s SEARCH (RFC 9051 §6.4.4; imap_key), for the mail a server holds and this device does not;
• the sentence that says what is searched (sentence): “Mail from …@bank.example…, arrived after 3 June, with an attachment.”;
• the key a message seen on its server only goes by until it is brought here (ServerRef, an IMAP URL, RFC 5092).

Structs

Form

What the search’s column offers, in your language: the filters’ fields the search uses and its own four, with their tests; the kinds of attachments, who a sender is, the marks, the folders’ purposes. The addresses and each one’s folders are the window’s to add.

Found

A message seen on its server only: its headers, its size, its marks, when it reached the server, and its attachments as the server describes them (BODYSTRUCTURE). Its text is not here.

Names

How the window names an address and a folder in a sentence.

Search

A search: the filters’ conditions, all of them (the default) or any of them.

ServerRef

A message on a server, by its account, its folder’s server name and its UIDVALIDITY and UID: imap://work/INBOX;UIDVALIDITY=7/;UID=42 (RFC 5092’s form, the account’s id standing for the server), each part percent-encoded.

Stored

A message stored here, read as little as its conditions need: its headers for most, the whole of it for its text and attachments.

Enums

ImapKey

A search key of IMAP’s SEARCH (RFC 9051 §6.4.4), its strings kept apart: they go quoted, or as literals when they are not ASCII.

Token

One word of a SEARCH command.

Constants

SCHEME 🔒

Functions

attached 🔒

The headers most messages with attachments wear, signed ones too: what a server without Gmail’s search is asked, the parts then checked here.

bare 🔒

A Message-ID without its angle brackets.

day 🔒

day_words 🔒

“3 June”, with its year when it is not this one’s.

earliest

The first day all the conditions leave in (its arrival): what is kept here since an earlier day needs no server.

form

imap_date

A day as IMAP writes dates: “3-Jun-2026”, English month names whatever your language (RFC 9051 §9, date-month).

imap_key

What to ask the server for one of an account’s folders: none when this search finds nothing there (a folder not named, the junk). gmail: the server knows Gmail’s own search.

imap_key_without_words

The same without words, for a server that refused them: the days, the sizes and the marks asked, the rest checked here. GreenMail, for one, reads FROM as a whole address and refuses a part of one (“@bank.example”).

imap_of 🔒

One condition as a server key: none when a server cannot say it (who the sender is to you, the day of the week): then the folder’s newest are asked, and checked here. A key may find more than the condition (what it finds is checked here, on its headers and parts), never less: what a server would leave out wrongly is not asked of it.

key_with 🔒

What to ask for a folder, each condition asked as of says (none: the server cannot say it, and it is checked here).

percent_decode 🔒

percent_encode 🔒

phrase 🔒

One condition in words: “from …@bank.example…”, “arrived after 3 June”; the filters’ own words for those the search does not offer (Condition::said).

place_holds 🔒

An address or folder condition, for a folder of an account.

read_header

The headers of a message file: what comes before the first empty line, read a little at a time, at most 256 KB.

scope 🔒

Whether a condition is about where a message is (its address, its folder), not the message.

sentence

What a search looks for, in a sentence: “Mail from …@bank.example…, arrived after 3 June, with an attachment.”

size_words 🔒

“5 MB”, “500 KB”, in your language’s units and decimals.

whole 🔒

Whether a condition reads the whole message (its text, its attachments), not its headers alone.