Skip to main content
Sets or clears the user-facing flags on up to 50 messages in one call: read / unread, to-do, and starred. Several flags go in one call, and a flag left out is untouched. Nothing else about a message changes: it stays in the folders it was in and keeps its classified type. Re-running it on the same ids is harmless. Reading a message never changes its read state on its own — get_email, get_thread and search_emails leave it as it was. The agent decides, with this tool: mark what it handled as read, mark a message unread to keep it for the user, flag a message that needs the user’s action as a to-do, and clear the to-do once it is done. To get a message out of the inbox use archive_emails or move_emails; finishing a to-do is usually todo: false here, then archive_emails. Only these three flags can be set. System flags that record what happened to a message (answered, draft) and classified types are not settable. For an account connected to Gmail, the to-do flag is written back to Gmail as the Todo label (unless mirroring is disabled for the account). Read state and stars set here stay in Langmail: they are not yet written back to Gmail, and changing them in Gmail later overrides them.

​
Parameters

​
string[]
required
1–50 message ids, as returned by search_emails or get_thread. Duplicates are collapsed.
​
boolean
true marks the messages read, false marks them unread. Leave out to keep read state.
​
boolean
true flags the messages as a to-do for the user, false clears the to-do. This is the flag search_emails filters on with keywords: ["todo"]. Leave out to keep it.
​
boolean
true stars the messages, false removes the star. Leave out to keep it.
At least one of read, todo and starred is required.

​
Example

Call — finish a to-do
Result
A batch is not all-or-nothing. Ids the server refused are listed with the reason, and the call only counts as an error when nothing was marked:
Result — one stale id

​
Errors

  • No flag given, so nothing was changed. Pass at least one of read, todo or starred. — the call named no flag.
  • Marked 0 message(s) as …. Not updated (N): … Re-run search_emails or get_thread for current ids. — every id was refused, typically because the messages no longer exist.