Select emails for a bulk action
select_emailsFind every message matching a search, up to 500 at a time, and return their UIDs grouped by folder and then by sender, for one bulk call per folder of delete_email, move_email, archive_email, mark_junk, not_junk, mark_read, mark_unread, flag_email or unflag_email. Each sender group gives the address and name, how many, how many unread and flagged, the delivery date range and up to 3 of its subjects, so what matched can be told to the user before anything changes; there are no previews or bodies. search_emails, by contrast, returns at most 100 full summaries, for finding particular messages. fromAny takes up to 20 senders, matched as alternatives; all: true takes every message in the named folders. Matching is by substring, as in search_emails, so a search can match senders it was not aimed at; each has its own group, except that senders past the 25 largest share one group that lists their addresses. A capped result says so, with the true total.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| cc | No | Substring match against the Cc address or display name. | |
| on | No | Delivered on exactly this date (e.g. "2026-08-01"). Matches when the message arrived in this mailbox, not its Date: header. | |
| to | No | Substring match against the To address or display name. | |
| all | No | true: every message in the named folders, with no other condition. Stated explicitly, because an empty call is refused. | |
| body | No | Substring match against the message body. | |
| from | No | One sender. Substring match against the From address or display name. | |
| seen | No | Filter by read/unread status. | |
| text | No | Substring match against headers and body together. | |
| limit | No | How many UIDs to return across all the folders, newest first within each. Defaults to 500, the most one write call takes. | |
| since | No | Delivered on or after this date (e.g. "2026-08-01"). Matches when the message arrived in this mailbox, not its Date: header. Whole-day precision only. | |
| before | No | Delivered before this date (e.g. "2026-08-01"). Matches when the message arrived in this mailbox, not its Date: header. Whole-day precision only. | |
| flagged | No | Filter by the flagged/starred state. | |
| fromAny | No | Up to 20 senders, any of them. Substring matches, as `from`. Not together with `from`. | |
| subject | No | Substring match against the subject line. | |
| answered | No | Filter by whether the message has been answered. | |
| mailboxes | No | IMAP folders to select from, e.g. ["INBOX"]. Defaults to ["INBOX"]. Up to 25 in one call. A write call acts on one folder, so each folder in the answer is one write call. |