---
title: "Batch Update Messages"
method: POST
path: "/v0/inboxes/{inbox_id}/messages/batch-update"
tags: ["InboxesMessages"]
---

# Batch Update Messages

`POST /v0/inboxes/{inbox_id}/messages/batch-update`

Apply one label change to up to 50 messages in a single request. The
same add_labels and remove_labels apply to every message id, and at
least one of them must be provided. The update is atomic: either all
resolved messages are updated or none are. Missing or restricted ids
are silently excluded; compare `count` against `limit` to detect
exclusions.

**CLI:**
```bash
agentmail inboxes:messages batch-update --inbox-id <inbox_id> --message-id <id1> --message-id <id2> --add-label read --remove-label unread
```

## Path parameters

- `inbox_id` string, required — The ID of the inbox.

## Request body

- BatchUpdateMessagesRequest
  - `message_ids` MessageId[], required — IDs of messages to update. Maximum 50 ids per request. Duplicates are rejected with a validation error. IDs not found in the inbox (including cross-inbox or permission-restricted) are silently excluded from the update; callers detect exclusions by comparing `count` against `limit`.
  - `add_labels` union — Label or list of labels.
    - string
    - string[]
  - `remove_labels` union — Label or list of labels.
    - string
    - string[]

## Response `200`

- BatchUpdateMessagesResponse
  - `limit` integer, required — Limit of number of items returned.
  - `count` integer, required — Number of items returned.
  - `updates` UpdateMessageResponse[], required — Updated messages with their new labels. Order matches `message_ids` in the request. Excluded ids are omitted, so `count` may be less than `limit`.
    - `message_id` string, required — ID of message.
    - `labels` string[], required — Labels of message.

## Other responses

- `400`

---

[API](https://skmtc.net/agentmail-to/apis/api.md) · [All operations](https://skmtc.net/agentmail-to/apis/api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/agentmail-to/api/revisions/394ddcdd9c29/schema)