:::endpoint POST /v1/me/mail/messages/{id}/notes

A note is never sent and never seen by whoever wrote in. It is what the team
tells each other about an exchange: what was agreed on the phone, why this one
is waiting, who already looked at it.

Addressed by message, like every other write here, because a message id is what
a client has to hand. The note lands on the conversation, so it is there
whichever message of the thread somebody opens next.

Whoever may read the mailbox may read and write its notes. Anything narrower
would mean a shared support mailbox where the remark explaining the situation is
invisible to the colleague who picks the conversation up, which is worse than no
remark at all.

Notes come back with [the conversation](/docs/api/mail/message), and a count of
them is on every row of [the list](/docs/api/mail/messages). There is no endpoint
for reading them on their own: a remark that arrives after somebody has started
typing their reply is a remark that did not do its job.

## Request

```bash
curl -X POST https://api.proppertrading.com/v1/me/mail/messages/1552/notes \
  -H "Authorization: Bearer ptat_9f2c1a44_3b8e7d2f5c9a1b4e6d8f0a2c4e6b8d1f" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 9c3d5e77-2b1a-4f8e-9d0c-1a2b3c4d5e6f" \
  -d '{"body": "Called them back, waiting on the bank statement."}'
```

| Field  | Type   | Description                                                                                   |
| ------ | ------ | --------------------------------------------------------------------------------------------- |
| `body` | string | Required, up to 5000 characters. Trimmed. Plain text: it is shown as written, never as markup |

## Response

`201`, and the note.

```json
{
    "data": {
        "id": 88,
        "object": "mail_note",
        "body": "Called them back, waiting on the bank statement.",
        "author": "Han Aarts",
        "author_id": 41,
        "is_mine": true,
        "can_edit": true,
        "created_at": "2026-08-20T14:02:11.000000Z",
        "edited": false
    },
    "meta": { "request_id": "req_01kz4bkr1aj1gv63d8fv3133ey" }
}
```

| Field       | Description                                                                                                                                       |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `author`    | The name as it was when the note was written, or the account's current name if it still exists. Null only if neither is known                     |
| `author_id` | The account behind the name, or null once that account is gone. A note always says who wrote it, and only sometimes has somebody left to point at |
| `is_mine`   | Whether the caller wrote it                                                                                                                       |
| `can_edit`  | Whether the caller may change it: their own, or anybody's with `manage_mailbox`                                                                   |
| `edited`    | Whether it has been rewritten since. Worth showing: a remark that changed is not the one the person above it agreed with                          |

## Errors

| Status | Code                      | Meaning                                       |
| ------ | ------------------------- | --------------------------------------------- |
| 400    | `missing_idempotency_key` | Every POST needs one                          |
| 403    | `insufficient_scope`      | This device does not hold `mail:write`        |
| 404    | `resource_not_found`      | No such message in a mailbox you can read     |
| 422    | `validation_failed`       | `body` missing, empty or over 5000 characters |