This endpoint allows you to list, create, update and delete message labels in your account.

Listing Labels

A GET returns the list of message labels for your organization, in the order of last created.

• uuid - the UUID of the label (string), filterable as uuid.
• name - the name of the label (string), filterable as name.
• count - the number of messages with this label (int).

Example:

GET /api/v2/labels.json

Response containing the labels for your organization:

{
    "next": null,
    "previous": null,
    "results": [
        {
            "uuid": "5f05311e-8f81-4a67-a5b5-1501b6d6496a",
            "name": "Screened",
            "count": 315
        },
        ...
    ]
}

Adding a Label

A POST can be used to create a new message label. Don't specify a UUID as this will be generated for you.

• name - the label name (string)

Example:

POST /api/v2/labels.json
{
    "name": "Screened"
}

You will receive a label object as a response if successful:

{
    "uuid": "fdd156ca-233a-48c1-896d-a9d594d59b95",
    "name": "Screened",
    "count": 0
}

Updating a Label

A POST can also be used to update an existing message label if you specify its UUID in the URL.

Example:

POST /api/v2/labels.json?uuid=fdd156ca-233a-48c1-896d-a9d594d59b95
{
    "name": "Checked"
}

You will receive the updated label object as a response if successful:

{
    "uuid": "fdd156ca-233a-48c1-896d-a9d594d59b95",
    "name": "Checked",
    "count": 0
}

Deleting a Label

A DELETE can be used to delete a message label if you specify its UUID in the URL.

Example:

DELETE /api/v2/labels.json?uuid=fdd156ca-233a-48c1-896d-a9d594d59b95

You will receive either a 204 response if a label was deleted, or a 404 response if no matching label was found.