## Render a mail exactly as it would be sent (desk:write, agent role)

`POST /api/desk/v1/items/{ref}/mail/preview`

Module: Desk · operationId: `previewItemMail` · Tag: Mail · Auth: access token (`Authorization: Bearer <accessToken>`)

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `ref` | path | string | yes | Item id or number |

### Request body

`application/json` (required)

- `aiGenerated` (boolean): The text was written with AI help
- `attachmentIds` (array of string): Documents of the ticket
- `bcc` (array of Address): Recipients in blind copy
  - `address` (string): E-mail address
  - `name` (string): Display name (may be empty)
- `body` (string): Markdown
- `cc` (array of Address): Recipients in copy
  - `address` (string): E-mail address
  - `name` (string): Display name (may be empty)
- `inReplyToEntryId` (string): The mail entry of the ticket this mail answers (threading). An internal mail answers only internal mails (422 public_thread). Empty on an existing draft keeps the mail it answers.
- `includeChain` (boolean): Add every earlier mail of the ticket the recipients may see (received and sent, public, no automatic answers or failed deliveries) below the text, newest first, Outlook style ("-----Original Message-----", Von, Gesendet, An, Cc, Betreff; never Bcc); at most 100 mails and 200 KB of text, older ones are left out with a note. An internal mail carries only its own thread (the mail it answers and its ancestors). Default true; stored with the mail and kept on a resend.
- `mailboxId` (string): Empty uses the default mailbox
- `send` (boolean): Send now; false saves a draft
- `signature` (boolean): Append the signature (default true)
- `subject` (string): Subject
- `to` (array of Address): Recipients
  - `address` (string): E-mail address
  - `name` (string): Display name (may be empty)
- `visibility` (string): internal: an internal mail to third parties (suppliers, …). It is sent, but the entry stays internal and is never shown to customers. It needs explicit recipients, none of them a participant of the ticket (422 recipient_is_participant on the field), its subject carries no [#N] token, its Reply-To an internal tag, and answers to it are stored internal. Empty: public, unless inReplyToEntryId is an internal mail (then internal; public is refused with 422 internal_thread). Saving or sending an existing draft with it empty keeps the draft's kind (internal or not); only an explicit value changes it. Kept on a resend. (one of `public`, `internal`)

Example:

```json
{
  "body": "Der Switch ist getauscht, alle Access Points laufen wieder stabil. Bitte geben Sie uns Bescheid, falls Gäste noch Probleme melden.",
  "includeChain": true,
  "send": true,
  "signature": true,
  "subject": "[#1] WLAN in den Gästezimmern 2. OG fällt immer wieder aus",
  "to": [
    {
      "address": "katrin.stadler@alpenhotel-seeblick.example",
      "name": "Katrin Stadler"
    }
  ],
  "visibility": "public"
}
```

### Responses

- **200** Rendered mail (`application/json`)

Fields of the 200 answer:

- `html` (string)
- `subject` (string)
- `text` (string)

Example 200 answer:

```json
{
  "html": "\u003cp\u003eDer Switch ist getauscht, alle Access Points laufen wieder stabil.\u003c/p\u003e\u003cp\u003eViele Grüße\u003cbr\u003eSophie Huber\u003c/p\u003e",
  "subject": "[#1] WLAN in den Gästezimmern 2. OG fällt immer wieder aus",
  "text": "Der Switch ist getauscht, alle Access Points laufen wieder stabil.\n\nViele Grüße\nSophie Huber"
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/desk/v1/items/string/mail/preview' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"body":"Der Switch ist getauscht, alle Access Points laufen wieder stabil. Bitte geben Sie uns Bescheid, falls Gäste noch Probleme melden.","includeChain":true,"send":true,"signature":true,"subject":"[#1] WLAN in den Gästezimmern 2. OG fällt immer wieder aus","to":[{"address":"katrin.stadler@alpenhotel-seeblick.example","name":"Katrin Stadler"}],"visibility":"public"}'
```
