Skip to navigation
API ReferenceInboxesMessages

Batch Update Messages

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:

agentmail inboxes messages batch-update --inbox-id <inbox_id> --message-ids <id1> --message-ids <id2> --add-labels read --remove-labels unread

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Path parameters

inbox_idstringRequired
The ID of the inbox.

Request

This endpoint expects an object.
message_idslist of stringsRequired

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_labelsstring or list of stringsOptional
Label or labels to add to every message.
remove_labelsstring or list of stringsOptional
Label or labels to remove from every message.

Response

This endpoint returns an object.
limitinteger
Limit of number of items returned.
countinteger
Number of items returned.
updateslist of objects

Updated messages with their new labels. Order matches message_ids in the request. Excluded ids are omitted, so count may be less than limit.

Errors

400
Validation Error