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, and a count of them is on every row of the list. 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

curl -X POST https://api.proppertrading.com/v1/me/mail/messages/msg_h3k8q2w7n4r9t5vx/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.

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

Field	Description
`id`	The note, such as `mnote_r8t4k2n7q3w9x5hb`. What edit and delete take in their path
`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, such as `usr_t7q3m8k2x9n4w6pb`, 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. A number in the path finds none either
422	`validation_failed`	`body` missing, empty or over 5000 characters

Add a note

Request

Response

Errors