:::endpoint POST /v1/me/mail/messages

Sends immediately and files a copy in Sent. Answering an existing message keeps
the reply in the same conversation, on both ends: leave `in_reply_to` out and the
recipient's mail client will file your answer as a new exchange.

:::warning Send the same Idempotency-Key on a retry
A phone on a train retries, and a retry without the key sends the same message
twice. With it, the second attempt gets the first one's answer back and nothing
leaves twice. See [Idempotency](/docs/api/idempotency).
:::

## Request

```bash
curl -X POST https://api.proppertrading.com/v1/me/mail/messages \
  -H "Authorization: Bearer ptat_9f2c1a44_3b8e7d2f5c9a1b4e6d8f0a2c4e6b8d1f" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7d8e9f01-2a3b-4c5d-6e7f-8091a2b3c4d5" \
  -d '{
    "address_id": 32,
    "to": ["jamie@example.com"],
    "cc": [],
    "subject": "Re: Payout request",
    "body": "<p>Your payout is on its way.</p>",
    "in_reply_to": 1552,
    "quoted": "<blockquote>Hi, I passed the evaluation last week.</blockquote>",
    "draft_id": 1576,
    "signature_id": 4
  }'
```

| Field          | Type    | Description                                                                                                                       |
| -------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `address_id`   | integer | The mailbox it goes out from. Required, and it has to be one of yours                                                             |
| `to`           | array   | One to fifty addresses. Required                                                                                                  |
| `cc`           | array   | Up to fifty. Optional                                                                                                             |
| `subject`      | string  | Required, up to 255 characters                                                                                                    |
| `body`         | string  | HTML. Required, up to 100000 characters                                                                                           |
| `in_reply_to`  | integer | The message being answered, so the reply stays in its conversation                                                                |
| `quoted`       | string  | The quoted half, kept apart from the body                                                                                         |
| `draft_id`     | integer | The draft this became. It turns into the sent message rather than being left behind                                               |
| `signature_id` | integer | Which sign-off to append, from [list signatures](/docs/api/mail/signatures). Left out or `null`, the message goes out without one |

`to` and `cc` also accept one string with commas or semicolons in it, which is
what a paste from somewhere else looks like.

Keep `quoted` out of `body`. They are sent apart so the message can be assembled
as body, signature, quote in that order, and so the reader on the other end can
fold the quote away.

A signature has to belong to the mailbox you are sending from, or to no mailbox
in particular, and to you, or to nobody in particular. Anything else is ignored
and the message goes out unsigned: a colleague's own sign-off is theirs, and an
id from another mailbox would put a name under a message its owner did not
write. [List signatures](/docs/api/mail/signatures) returns exactly the ones that
pass, and says which one the mailbox would start you on.

## Response

```json
{
    "data": {
        "id": 1580,
        "object": "mail_message",
        "thread_id": 611,
        "address_id": 32,
        "folder": "sent",
        "subject": "Re: Payout request",
        "to_recipients": [{ "email": "jamie@example.com", "name": null }],
        "cc_recipients": [],
        "message_at": "2026-08-19T18:22:04.000000Z"
    },
    "meta": { "request_id": "req_01kz4bkr1aj1gv63d8fv3133ey" }
}
```

Status is `201`. Sending also marks the conversation as answered, by you.

## Errors

| Status | Code                      | Meaning                                                                         |
| ------ | ------------------------- | ------------------------------------------------------------------------------- |
| 400    | `missing_idempotency_key` | Every POST needs one                                                            |
| 400    | `not_a_draft`             | `draft_id` points at a message that is not a draft                              |
| 403    | `insufficient_scope`      | This device does not hold `mail:write`                                          |
| 404    | `resource_not_found`      | The mailbox, the message being answered or the draft is not one of yours        |
| 422    | `validation_failed`       | Something is missing or malformed                                               |
| 500    | `send_failed`             | The provider would not take it. The draft is still there, so offer to try again |