:::endpoint 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](/docs/api/mail/label) 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

```bash
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](/docs/api/mail/labels) returns it.

```json
{
    "data": {
        "id": 10,
        "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 |