POST/v1/me/mail/labels

Labels belong to the environment, so a new one appears for everybody who can open a mailbox in it. Nothing here touches a message: use label a conversation for that.

Anybody who can read a mailbox can make one. That is on purpose. Somebody working a shared inbox invents "Payouts" on the morning the payout questions start, and a rule that sends them to find an administrator first is a rule that produces an inbox with no labels in it.

There is no endpoint for renaming or removing one yet. Both live in the admin screens.

Request

curl -X POST https://api.proppertrading.com/v1/me/mail/labels \
  -H "Authorization: Bearer ptat_9f2c1a44_3b8e7d2f5c9a1b4e6d8f0a2c4e6b8d1f" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 9c3d5e77-2b1a-4f8e-9d0c-1a2b3c4d5e6f" \
  -d '{"name": "Payouts", "color": "blue"}'

Field	Type	Description
`name`	string	Up to 40 characters. Compared without case, so `payouts` collides with an existing `Payouts`
`color`	string	One of `gray`, `red`, `orange`, `amber`, `emerald`, `cyan`, `blue`, `violet`, `pink`. The palette is fixed so a label looks the same in every client

Response

201, and the label as the list returns it.

{
    "data": {
        "id": "lbl_p6m3x8b2k9q4w7td",
        "object": "mail_label",
        "name": "Payouts",
        "color": "blue"
    },
    "meta": { "request_id": "req_01kz4bkr1aj1gv63d8fv3133ey" }
}

Errors

Status	Code	Meaning
400	`missing_idempotency_key`	Every POST needs one
403	`insufficient_scope`	This device does not hold `mail:write`
403	`mailbox_not_permitted`	This account may not open a mailbox
422	`validation_failed`	The name is missing, too long or already taken, or the colour is not in the palette

Create a label

Request

Response

Errors