Set mail flags
set_mail_flagsSet email read/unread and star status, and add, remove, or replace keywords/tags. Reversible changes tracked via requestId for safe retries.
Instructions
Marks one email read or unread, stars or unstars it, and adds, removes, or replaces its keywords — the labels a mail client shows as tags. Every value is optional and at least one is required; a call that names none is refused. The change is written down durably and issued to the mail server by the account's next synchronization run, so the result reports the records rather than a mailbox that has already changed: each carries a changeRecordId and the lifecycle it has reached. To read where a change has got to, call again with the same requestId, which answers with the same records and their current lifecycle. Every change is reversible: call again with the opposite value. keywordChange replace states the whole keyword set — a keyword you do not list is removed, and an empty list clears them all — so read the email's keywords first, or use add and remove, which touch only what they name. Only these three values can be written: this tool never sets the answered or draft flags, never deletes mail, and never sends anything.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| seen | No | true marks the email read, false marks it unread. Omit it to leave the flag where it stands. Reading mail through MailFathom never sets it, so this is the only way it moves from here. | |
| flagged | No | true stars the email, false unstars it. This is the flag a mail client draws as a star or a flag, and it is what the owner will see in their own client. | |
| keywords | No | The keywords the change names, at most 64, each at most 64 characters. A keyword is an IMAP atom: no space, no control character, none of ( ) { % * " \ ], nothing above plain ASCII, and no leading backslash, which is how system flags are spelled. Two spellings differing only in case are one keyword. An empty list is accepted only with replace, where it clears every keyword. | |
| requestId | No | Your own identifier for this request, at most 128 characters. Send the same one when retrying a call that may have gone through: the change is then the same request and is not made twice. A call with a new value, or with none, is a new request — which is what lets you star a message, unstar it, and star it again. Reusing one to ask for a different value is refused, so send a new identifier whenever you mean a new change. | |
| keywordChange | No | What to do with keywords: add puts the listed ones on beside whatever the email already carries, remove takes the listed ones off and leaves the rest, replace makes the keywords exactly the listed ones. Send it together with keywords; either one alone is refused. | |
| storedEmailId | Yes | The storedEmailId a listing, a search, or a read returned for the email. A UUID that does not change when the mail server renumbers or moves the message. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| accountId | Yes | The account the email belongs to. Its next synchronization run is what issues the change to the mail server. | |
| folderAlias | Yes | The folder alias the email is in, as MailFathom's configuration names it. | |
| storedEmailId | Yes | The storedEmailId the change was recorded against, which is the one the call named. | |
| recordedChanges | Yes | One entry per value asked for, in the order seen, flagged, keywords. A call that asked for one value carries one entry. |