Act On Thread

POST

/onebox/action

Apply an action to one or more threads — mark read, star, move, label.

threadMessages maps each threadId to the list of messageId values within it that the action should apply to, so you can act on a single message or a whole thread.

Known action values

read and unread are confirmed working against Gmail. The accepted vocabulary is enforced by the mail backend rather than by CMR, so an unrecognised value returns 400 with "action is required and must be a valid email action". Values that move or label mail take the data object.

Example

{
  "userId": "K5PF9Y068AMDGENV5BTCNJJZK55F",
  "account": "andrew.lawyer@aurumlawyer.com",
  "threadMessages": {
    "1877937258181177440": ["<Gq3K93hRllxHkWlnjYO1wg@notifications.google.com>"]
  },
  "action": "read"
}

Request

Authorization

API Key

Add parameter in header

cmr-x-api-key

Example:

cmr-x-api-key: ********************

Body Params application/jsonRequired

Examples

Responses

🟢200Success

application/json

Action applied. results holds one entry per thread, in request order.

Bodyapplication/json

🟠400Invalid action

🟠401Unauthorized

🟠404Not Found

🟠422Validation Error

Request Example

Shell

JavaScript

Java

Swift

curl --location 'https://customers.coldmailreseller.com/api/v1/integration/onebox/action' \
--header 'cmr-x-api-key: <api-key>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "userId": "K5PF9Y068AMDGENV5BTCNJJZK55F",
    "account": "andrew.lawyer@aurumlawyer.com",
    "threadMessages": {
        "1877937258181177440": [
            "<Gq3K93hRllxHkWlnjYO1wg@notifications.google.com>"
        ]
    },
    "action": "read",
    "data": {
        "folder": "archive",
        "label": "important"
    }
}'

Response Example

200 - Example 1

{
    "status": 200,
    "message": "Action applied",
    "data": {
        "message": "1 of 1 threads updated successfully.",
        "results": [
            {
                "success": true
            }
        ]
    }
}

Modified at 2026-10-02 12:23:00

Search Emails

List Labels

Act On Thread

Known action values#

Example#

Request

Responses

Known action values

Example