API Explorer
Message Actions Endpoint

Bulk Message Updating

A POST can be used to perform an action on a set of messages in bulk.

  • messages - the message ids (array of up to 100 integers)
  • action - the action to perform, a string one of:

    • label - Apply the given label to the messages
    • unlabel - Remove the given label from the messages
    • archive - Archive the messages
    • restore - Restore the messages if they are archived
    • delete - Permanently delete the messages
  • label - the UUID or name of an existing label (string, optional)

  • label_name - the name of a label which can be created if it doesn't exist (string, optional)

If labelling or unlabelling messages using label you will get an error response (400) if the label doesn't exist. If labelling with label_name the label will be created if it doesn't exist, and if unlabelling it is ignored if it doesn't exist.

Example:

POST /api/v2/message_actions.json
{
    "messages": [1234, 2345, 3456],
    "action": "label",
    "label": "Testing"
}

You will receive an empty response with status code 204 if successful. In the case that some messages couldn't be updated because they no longer exist, the status code will be 200 and the body will include the failed message ids:

Example response:

{"failures": [2345, 3456]}