:::endpoint PATCH /v1/me/mail/messages/{id}

Three changes in one call, because a phone makes several of them in a row while
somebody swipes through a list, and three round trips is three chances to be
halfway done when the signal drops.

Everything is optional and only what you send is applied. Leave out `is_read`
and it stays whatever it was, rather than being reset to a value you read a
minute ago.

## Request

```bash
curl -X PATCH https://api.proppertrading.com/v1/me/mail/messages/1552 \
  -H "Authorization: Bearer ptat_9f2c1a44_3b8e7d2f5c9a1b4e6d8f0a2c4e6b8d1f" \
  -H "Content-Type: application/json" \
  -d '{"is_starred": true, "folder": "trash", "conversation": true}'
```

| Field          | Type    | Description                                                             |
| -------------- | ------- | ----------------------------------------------------------------------- |
| `is_starred`   | boolean | Star or unstar                                                          |
| `is_read`      | boolean | Mark read or unread                                                     |
| `folder`       | string  | `inbox`, `drafts`, `sent`, `spam` or `trash`                            |
| `conversation` | boolean | Apply to the whole exchange rather than this message. Defaults to false |

`conversation` reaches the messages that belong to the exchange as this view
sees it: the bin only reaches the bin, spam only reaches spam, and everywhere
else it is the inbox, the drafts and your own replies together. Which messages
those are is worked out from the id in the path, never from a list you send.

## Response

The message as a list row, so it can go straight back into the list you already
hold instead of costing a refetch.

```json
{
    "data": {
        "object": "mail_message",
        "id": 1552,
        "thread_id": 611,
        "folder": "trash",
        "is_starred": true,
        "is_read": true,
        "position": 1,
        "count": 3
    },
    "meta": { "request_id": "req_01kz4bkr1aj1gv63d8fv3133ey" }
}
```

## Moving to the bin is not deleting

Moving to `trash` writes down where the message came from, which is what makes
[putting it back](/docs/api/mail/restore) possible. Erasing for good is
[its own call](/docs/api/mail/erase) and only works out of the bin.

## Errors

| Status | Code                    | Meaning                                   |
| ------ | ----------------------- | ----------------------------------------- |
| 403    | `insufficient_scope`    | This device does not hold `mail:write`    |
| 403    | `mailbox_not_permitted` | The account may not open a mailbox at all |
| 404    | `resource_not_found`    | No such message in a mailbox you can read |
| 422    | `validation_failed`     | `folder` is not one of the five           |