List emails
list_emailsRead-onlyIdempotent
List email summaries from a local mailbox copy, filtered by account, folder, sender, recipient, subject, date, flags, keyword, or attachments. Reads local copy only, never contacting the mail server.
Instructions
Lists summaries of emails already synchronized into MailFathom's local mailbox copy, newest received first by default. Filters 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 body text, raw MIME, or attachment content. Mail in the account's junk folder is left out unless includeJunkMail is set. Returns at most 100 summaries per call, with an opaque cursor for the next page and a per-folder statement of how current the local copy is.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| cursor | No | The nextCursor value from a previous call, to read the following page. Reuse it only with the same filters and direction; presenting it with different ones is refused. Changing only the page size is allowed. | |
| folders | No | MailFathom folders to read, 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 reads whichever folder each account in scope maps with that role, whatever it is called there. Omit to read 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 read, each named by its configured account identifier or by the display name it is published under. Omit to read 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 page. | |
| pageSize | No | How many summaries to return, from 1 to 100. Omit to take the default of 25. A value outside the range is refused rather than clamped. | |
| direction | No | Which end of the timeline to read from: newestFirst to browse recent mail, oldestFirst to walk a mailbox in full. | newestFirst |
| 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. Listing 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. A cursor issued with one answer cannot be presented with the other. 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. Wildcard characters match themselves. 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 |
|---|---|---|---|
| emails | Yes | The email summaries on this page, in the requested order. Empty when no email matched the filters. | |
| nextCursor | No | An opaque cursor for the next page. Pass it back unchanged as cursor, with the same filters. Null means this page ended the walk. A present cursor does not promise that the next page is non-empty, because mail can be expunged between two calls, but continuing from it never skips or repeats an email. | |
| 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 listing. False means its mail was left out and is reachable by calling again with includeJunkMail set. |