POST /api/v1.0/flag — messages-api

flags

Change a specific flag (unread, starred, trashed, archived, spam) for multiple messages or all messages within multiple threads. Uses request body.

post/api/v1.0/flag/

Request body

flag'unread' | 'starred' | 'trashed' | 'archived' | 'spam' required

unread - unread
starred - starred
trashed - trashed
archived - archived
spam - spam

valueboolean required

message_idsstring[]

List of message UUIDs to apply the flag change to.

thread_idsstring[]

List of thread UUIDs where all messages should have the flag change applied.

mailbox_idstring uuid

Mailbox UUID. Required when flag is 'unread' or 'starred'.

read_atstring date-time nullable

Timestamp up to which messages are considered read. When provided with flag='unread', sets ThreadAccess.read_at directly. null means nothing has been read (all messages unread).

starred_atstring date-time nullable

Timestamp when the thread was starred. When provided with flag='starred' and value=true, sets ThreadAccess.starred_at. null or value=false removes the starred flag.

Response

object required

Unspecified response body

Changes

Changed in 7 of the 54 revisions of this API.4414

Mar 3, 202695d67b78149c6See the full diff
- ○
  added the new optional request property mailbox_id (media type: application/json)
  new-optional-request-property
- ○
  added the new optional request property mailbox_id (media type: multipart/form-data)
  new-optional-request-property
- ○
  added the new optional request property read_at (media type: application/json)
  new-optional-request-property
- ○
  added the new optional request property read_at (media type: multipart/form-data)
  new-optional-request-property
- ○
  added the new optional request property starred_at (media type: application/json)
  new-optional-request-property
- ○
  added the new optional request property starred_at (media type: multipart/form-data)
  new-optional-request-property
Mar 3, 2026e6feb47a0d7e4See the full diff
- ●
  removed the request property mailbox_id (media type: application/json)
  request-property-removed
- ●
  removed the request property mailbox_id (media type: multipart/form-data)
  request-property-removed
- ●
  removed the request property read_at (media type: application/json)
  request-property-removed
- ●
  removed the request property read_at (media type: multipart/form-data)
  request-property-removed
This revision also has 1 change that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog
Feb 25, 2026575958bae4594See the full diff
- ○
  added the new optional request property mailbox_id (media type: application/json)
  new-optional-request-property
- ○
  added the new optional request property mailbox_id (media type: multipart/form-data)
  new-optional-request-property
- ○
  added the new optional request property read_at (media type: application/json)
  new-optional-request-property
- ○
  added the new optional request property read_at (media type: multipart/form-data)
  new-optional-request-property
Jan 24, 2026978ec5cc8f372See the full diff
- ○
  added the new spam enum value to the request property flag (media type: application/json)
  request-property-enum-value-added
- ○
  added the new spam enum value to the request property flag (media type: multipart/form-data)
  request-property-enum-value-added
Jan 14, 2026bf06662ebc552See the full diff
- ▲
  removed the enum value spam of the request property flag (media type: application/json)
  request-property-enum-value-removed
- ▲
  removed the enum value spam of the request property flag (media type: multipart/form-data)
  request-property-enum-value-removed
Jan 13, 2026d8748a28f71f2See the full diff
- ○
  added the new spam enum value to the request property flag (media type: application/json)
  request-property-enum-value-added
- ○
  added the new spam enum value to the request property flag (media type: multipart/form-data)
  request-property-enum-value-added
Jan 12, 20268b9ed8ea9a422See the full diff
- ▲
  removed the enum value spam of the request property flag (media type: application/json)
  request-property-enum-value-removed
- ▲
  removed the enum value spam of the request property flag (media type: multipart/form-data)
  request-property-enum-value-removed
This revision also has 1 change that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

Full history