Add or remove labels

POST/api/v1/mailbox/messages/{message_id}/labels

Requires amailbox token— it acts as one mailbox holder, not as the organization.

Adds and removes labels on one message in a single call. Labels are tidied: lower case, spaces become _, other symbols are dropped, 40 characters at most. System flags such as \Seen are refused (use mark-read).

Errors

Status	When
`401`	No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`.
`403`	The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`.
`400`	Neither `add` nor `remove` has a valid label.
`404`	Message not found.

Parameters

Name	In	Type	Description
`message_id`required	path	string

Request body

addarray<string>
Labels to add, up to 20.
removearray<string>
Labels to remove, up to 20.

Request

POST/api/v1/mailbox/messages/{message_id}/labels

curl -X POST 'https://courier.mailyte.com/api/v1/mailbox/messages/01JBT8XQ2M9WYC3K4F6R7S8T9V/labels' \
  -H 'Authorization: Bearer MAILBOX_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "add": [
      "invoices"
    ],
    "remove": [
      "follow-up"
    ]
  }'

const response = await fetch('https://courier.mailyte.com/api/v1/mailbox/messages/01JBT8XQ2M9WYC3K4F6R7S8T9V/labels', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer MAILBOX_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "add": [
      "invoices"
    ],
    "remove": [
      "follow-up"
    ]
  }),
});
const { data } = await response.json();

import requests
response = requests.post(
    "https://courier.mailyte.com/api/v1/mailbox/messages/01JBT8XQ2M9WYC3K4F6R7S8T9V/labels",
    headers={"Authorization": "Bearer MAILBOX_TOKEN"},
    json={
      "add": [
        "invoices"
      ],
      "remove": [
        "follow-up"
      ]
    },
)
data = response.json()["data"]

<?php

$response = Http::withToken('MAILBOX_TOKEN')
    ->post('https://courier.mailyte.com/api/v1/mailbox/messages/01JBT8XQ2M9WYC3K4F6R7S8T9V/labels', [
    'add' => [
        'invoices',
    ],
    'remove' => [
        'follow-up',
    ],
]);

$data = $response->json('data');

require "net/http"
require "json"
uri = URI("https://courier.mailyte.com/api/v1/mailbox/messages/01JBT8XQ2M9WYC3K4F6R7S8T9V/labels")
request = Net::HTTP::Post.new(uri)
request["Authorization"] = "Bearer MAILBOX_TOKEN"
request["Content-Type"] = "application/json"
request.body = {
  "add": [
    "invoices"
  ],
  "remove": [
    "follow-up"
  ]
}.to_json
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(request) }

Response

Successful Response

dataobject
- addedarray<string>
- removedarray<string>

200application/json

{
  "type": "success",
  "msg": "Labels updated",
  "data": {
    "added": [
      "invoices"
    ],
    "removed": [
      "follow-up"
    ]
  }
}

Returned inside the standard envelope.

Errors

Status	When
`400`	Neither `add` nor `remove` has a valid label.
`401`	No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`.
`403`	The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`.
`404`	Message not found.
`422`	Validation Error

Every status, with what causes it and what to do, is on the error reference.