Search emails
search_emailsRead-onlyIdempotent
Search synchronized email copies for words or phrases and receive ranked results with body snippets; narrow by sender, subject, date, and more without contacting a mail server.
Instructions
Searches the emails already synchronized into MailFathom's local mailbox copy for text, and returns the best matches ranked by relevance with bounded extracts of the body around the matched words. Retrieval is lexical or hybrid depending on how this server is configured, and every response says which in its retrievalMode field: lexical finds the words a query contains rather than what they mean, while hybrid also finds mail whose meaning is close and combines the two rankings. Words that appear only inside an attachment are never searchable either way. Narrows by account, folder, sender address, recipient address, subject text, received date range, remote seen state, remote flagged (starred) state, a keyword the mail server reported, and attachment presence. Reads the local copy only: it never contacts a mail server, never marks mail as read, and never returns whole bodies, raw MIME, or attachment content. Mail in the account's junk folder is left out unless includeJunkMail is set. Returns one window of at most 50 results that nothing continues, so narrow the filters or write a different query to reach other mail. Matching nothing is a normal empty result rather than an error.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| folders | No | MailFathom folders to search, each named by its alias, such as INBOX, or by the role it plays, written as role:Junk. Roles are Inbox, Archive, Drafts, Sent, Junk, Trash, All, Flagged, Important, and Outbox; naming one searches whichever folder each account in scope maps with that role, whatever it is called there. Omit to search every folder of the accounts in scope. At most 64 may be named. An alias is MailFathom's own name for a folder and is matched without regard to case. | |
| keyword | No | Return only emails carrying this keyword, which is a flag a mail client or server set rather than one of the five standard ones, such as $Junk or a label. Matched as a whole keyword without regard to case; up to 64 characters, and a value that is not a keyword this system stores is refused. Omit to match any, which an empty string does too. The keywords each email carries are reported in its remoteFlags. | |
| accounts | No | MailFathom accounts to search, each named by its configured account identifier or by the display name it is published under. Omit to search every account this deployment serves; call list_accounts to see what they are. At most 64 may be named, and a name this deployment does not serve is refused rather than answered with an empty window. | |
| queryText | Yes | The text to search for, up to 512 characters. Quoted phrases, OR, and a leading - to exclude a word are understood; every other punctuation mark is ordinary text. Write the words the mail itself is likely to contain, in the language it was written in rather than the language of your request: matching compares words rather than translating them, so a mailbox holding several languages is reached by a search per language. Required: a search with no text is a listing, which list_emails answers in a stable order and with a cursor. | |
| resultLimit | No | How many ranked results to return, from 1 to 50. Omit to take the default of 20. A value outside the range is refused rather than clamped, so a window is never smaller than it claims to be. | |
| senderAddress | No | Return only emails sent from this mail address. Matched as a whole address rather than as a fragment, without regard to case; a non-empty value that is not a usable mail address is refused. Omit to match any sender, which an empty string does too. | |
| hasAttachments | No | Return only emails that carry attachments (true) or that carry none (false). Omit to match either. Inline images and cryptographic signature parts do not count as attachments. | |
| isRemotelySeen | No | Return only emails the mail server last reported as read (true) or unread (false). Omit to match either. Searching never changes this state. An email whose flags no run has observed yet counts as unread. | |
| receivedBefore | No | Return only emails received strictly before this ISO 8601 timestamp, so consecutive ranges built from one instant neither overlap nor leave a gap. Omit for no upper bound. | |
| includeJunkMail | No | Include mail in the account's junk folder, which is left out by default. Naming the junk folder in folderAliases does not include it; only this does. The result reports which answer produced it. | |
| subjectFragment | No | Return only emails whose subject contains this text, without regard to case, up to 256 characters. This narrows which emails are eligible before any of them is ranked and is unrelated to queryText, which is what the eligible ones are matched against. Omit to match any subject, which an empty string does too. | |
| recipientAddress | No | Return only emails addressed to this mail address in their To or Cc header. Matched as a whole address rather than as a fragment; Reply-To is not searched. Omit to match any recipient, which an empty string does too. | |
| isRemotelyFlagged | No | Return only emails the mail server last reported as flagged (true) or unflagged (false), which is the star most mail clients show. Omit to match either. This is the \Flagged flag on a message and is unrelated to the Flagged folder role; an email whose flags no run has observed yet counts as unflagged. | |
| receivedOnOrAfter | No | Return only emails received at or after this ISO 8601 timestamp. Emails whose received date is unknown are excluded whenever either bound is named. Omit for no lower bound. |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| matches | Yes | The matched emails, most relevant first, ties broken by the newest received. Empty when nothing matched the query and the filters, which is a normal answer. | |
| retrievalMode | Yes | How these results were retrieved. 'lexical' means full-text matching over the words the mail is written in: a query term that appears nowhere in a message will not find it however close its meaning. 'hybrid' means that ranking was combined with a search by embedding similarity, so a message can appear without carrying the query's words. Read this field on every response rather than assuming a mode: the same server answers 'lexical' when its embedding provider is unavailable, and neither mode involves a chat model or rewrites the query. | |
| semanticSearch | Yes | What this server can do with embeddings, which is what tells you why a 'lexical' answer was lexical. 'inactive' means the server does not embed mail at all, so lexical is the intended and only mode. 'available' means it does and its provider is answering. 'degraded' means it does, but it currently cannot reach the embedding provider or its configuration is wrong, so these results are narrower than the server intends: say so rather than retrying, because nothing about the request caused it and the server's operator has to fix it. | |
| folderFreshness | Yes | How current the local copy of each folder in the request's scope is, one entry per folder. Read this before concluding that a mailbox holds no matching mail. | |
| includedJunkMail | Yes | Whether the account's junk folder took part in this search. False means its mail was left out and is reachable by calling again with includeJunkMail set. |