Skip to main content

​
Overview

Modifies message flags (e.g., \Seen, \Flagged, \Draft, custom flags) by adding or removing flags from a message. This is a non-destructive write operation that changes message metadata without affecting the message content.
This tool requires MAIL_IMAP_WRITE_ENABLED=true to be set in your environment variables. Write operations are disabled by default as a safety measure.

​
Common use cases

  • Mark messages as read/unread (\Seen)
  • Flag messages for follow-up (\Flagged)
  • Mark messages as drafts (\Draft)
  • Add custom labels or tags
  • Remove incorrect or outdated flags

​
Input parameters

​
body.account_id
string
default:"default"
Account identifier. Must match pattern ^[A-Za-z0-9_-]{1,64}$.
​
body.message_id
string
required
Message identifier in format imap:{account_id}:{mailbox}:{uidvalidity}:{uid}.The account_id in the message_id must match the account_id parameter.
​
body.add_flags
string[]
Array of flags to add (1-20 flags). At least one of add_flags or remove_flags is required.Common system flags:
  • \Seen - Message has been read
  • \Answered - Message has been replied to
  • \Flagged - Message is flagged for urgent/special attention
  • \Deleted - Message is marked for deletion
  • \Draft - Message is a draft
  • \Recent - Message is recent (read-only, cannot be set)
Custom flags must not contain whitespace, control characters, quotes, parentheses, or braces.
​
body.remove_flags
string[]
Array of flags to remove (1-20 flags). At least one of add_flags or remove_flags is required.Uses the same flag format as add_flags.

​
Response

​
summary
string
Human-readable one-line outcome: "Flags updated"
​
data
object
​
meta
object

​
Example request

{
  "account_id": "default",
  "message_id": "imap:default:INBOX:1234567890:42",
  "add_flags": ["\\Seen", "\\Flagged"]
}

​
Example response

{
  "summary": "Flags updated",
  "data": {
    "status": "ok",
    "issues": [],
    "account_id": "default",
    "message_id": "imap:default:INBOX:1234567890:42",
    "flags": ["\\Seen", "\\Flagged"],
    "requested_add_flags": ["\\Seen", "\\Flagged"],
    "requested_remove_flags": [],
    "applied_add_flags": true,
    "applied_remove_flags": false
  },
  "meta": {
    "now_utc": "2026-03-03T22:30:15.123Z",
    "duration_ms": 234
  }
}

​
Error responses

{
  "error": {
    "code": "invalid_input",
    "message": "write tools are disabled; set MAIL_IMAP_WRITE_ENABLED=true",
    "details": {}
  },
  "meta": {
    "now_utc": "2026-03-03T22:30:15.123Z",
    "duration_ms": 5
  }
}

​
Implementation notes

  • Flag operations use the +FLAGS.SILENT and -FLAGS.SILENT IMAP commands to avoid unnecessary server notifications
  • The server attempts to add flags first, then remove flags
  • Each operation is tracked separately with applied_add_flags and applied_remove_flags boolean indicators
  • After flag modifications, the server fetches the current flag list to return in the response
  • Flag validation prevents IMAP command injection by rejecting flags with special characters
  • The mailbox is selected in read-write mode, and uidvalidity is verified to ensure the message still exists

​
See also

Build docs developers (and LLMs) love

Get started for freeTalk to us