---
title: "POST /api/v1.0/flag/"
method: POST
path: "/api/v1.0/flag/"
tags: ["flags"]
---

# POST /api/v1.0/flag/

`POST /api/v1.0/flag/`

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

## Request body

- ChangeFlagRequestRequest
  - `flag` 'unread' | 'starred' | 'trashed' | 'archived' | 'spam', required — * `unread` - unread * `starred` - starred * `trashed` - trashed * `archived` - archived * `spam` - spam
  - `value` boolean, required
  - `message_ids` string[] — List of message UUIDs to apply the flag change to.
  - `thread_ids` string[] — List of thread UUIDs where all messages should have the flag change applied.
  - `mailbox_id` string, uuid — Mailbox UUID. Required when flag is 'unread' or 'starred'.
  - `read_at` string, 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_at` string, 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 `200`

- object — Unspecified response body

## Other responses

- `400`
- `403`

## Changes

- **2026-03-03** `95d67b78149c` — 6 info
  - added the new optional request property `mailbox_id` (media type: application/json)
  - added the new optional request property `mailbox_id` (media type: multipart/form-data)
  - added the new optional request property `read_at` (media type: application/json)
  - added the new optional request property `read_at` (media type: multipart/form-data)
  - …2 more
- **2026-03-03** `e6feb47a0d7e` — 4 warning
  - removed the request property `mailbox_id` (media type: application/json)
  - removed the request property `mailbox_id` (media type: multipart/form-data)
  - removed the request property `read_at` (media type: application/json)
  - removed the request property `read_at` (media type: multipart/form-data)
- **2026-02-25** `575958bae459` — 4 info
  - added the new optional request property `mailbox_id` (media type: application/json)
  - added the new optional request property `mailbox_id` (media type: multipart/form-data)
  - added the new optional request property `read_at` (media type: application/json)
  - added the new optional request property `read_at` (media type: multipart/form-data)
- **2026-01-24** `978ec5cc8f37` — 2 info
  - added the new `spam` enum value to the request property `flag` (media type: application/json)
  - added the new `spam` enum value to the request property `flag` (media type: multipart/form-data)
- …earlier changes not shown

[Full history](https://skmtc.dev/betagouv/apis/messages-api/changes/api/v1.0/flag/post.md)

---

[API](https://skmtc.dev/betagouv/apis/messages-api.md) · [All operations](https://skmtc.dev/betagouv/apis/messages-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/betagouv/messages-api/revisions/ba0c140b76dd/schema)