## Send a mail to the callback's contact (desk:write)

`POST /api/desk/v1/callbacks/{id}/customer-mail`

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

Sends subject and body to the e-mail address of the callback's contact in masterdata at the callback's
`version` (which stays). The `Idempotency-Key` header is required (at most 200 characters, no control
characters): the same key sends and records once, a retry answers the callback without sending again. The mail
is queued through comms and noted in the history (`customer_mail`).

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `Idempotency-Key` | header | string | yes | (max length 200) |
| `id` | path | string (uuid) | yes |  |

### Request body

`application/json` (required)

- `body` (string, required): (max length 8000)
- `subject` (string, required): (max length 200)
- `version` (integer, required)

Example:

```json
{
  "body": "Guten Tag Frau Stadler,\n\nwir haben heute versucht, Sie zurückzurufen, Sie aber leider nicht erreicht. Wir melden uns morgen wieder.\n\nViele Grüße\nElias Gruber",
  "subject": "Ihr Rückrufwunsch bei Muster IT",
  "version": 3
}
```

### Responses

- **200** Sent (`application/json`)
- **400** invalid: missing or invalid Idempotency-Key, subject or body (`application/json`)
- **404** Error (`application/json`)
- **409** version_conflict (`application/json`)
- **422** no_recipient: the contact has no usable e-mail address (no contact, gone, inactive, blocked or without address); mail_unavailable: mail (comms) is not set up for desk (`application/json`)
- **503** unavailable: masterdata is not reachable; retry with the same Idempotency-Key (`application/json`)

Fields of the 200 answer:

- `closed` (boolean, read-only): The status carries the closed flag
- `closedAt` (string (date-time), nullable): When the callback was closed
- `closedBy` (string): Login (e-mail) of who closed the callback
- `contact` (object): Masterdata contact snapshot (only with a customer)
- `contactName` (string): Name of the person to call back
- `convertedAt` (string (date-time), nullable): When the callback was turned into a ticket
- `createdAt` (string (date-time)): When the callback was created
- `createdBy` (string): Login (e-mail) of who created the callback
- `createdByName` (string): Name of who created the callback
- `customFields` (object): Values of the fields of settings.callbacks.fields, keyed without cf.
- `customer` (object): Masterdata address snapshot
- `customerMail` (object): Only in the answer of a create or status change into a status with a customer mail: the draft of a manual mail; for an automatic one the mail as queued (`mode` `auto`, no `missing`) or, when it was not sent, why (`missing`). Never on reads.
- `desiredAt` (string (date-time), nullable): When the contact wants to be called back
- `desiredHasTime` (boolean): false: only the day of desiredAt counts
- `doneNote` (string): Result of the call
- `id` (string (uuid)): Id of the callback
- `item` (ItemSummary)
  - `id` (string): Id of the item
  - `number` (integer): Number of the item
  - `phase` (Phase): (one of `new`, `active`, `waiting`, `done`)
  - `spaceId` (string): Space of the item
  - `status` (string): Status key
  - `title` (string): Title
  - `typeId` (string): Type of the item
- `itemId` (string, nullable): The ticket it became
- `note` (string): Note of the callback
- `number` (integer): Per tenant
- `origin` (string): The call it was made from in Arbeitsplatz › Aktivitäten (`comms:interaction:<id>`, `comms:calendar:<id>`); "" none
- `overdue` (boolean, read-only): Open and the desired time (without time: the desired day) has passed
- `phone` (string): Phone number to call back
- `reason` (string): Key of a callbackReason entry, "" = none
- `responsibleName` (string): Name of the person responsible
- `responsibleRef` (string): User ref of the person who calls back; "" = nobody yet (the pool of unassigned callbacks)
- `status` (string): Key of a callbackStatus entry
- `updatedAt` (string (date-time)): When the callback was last changed
- `version` (integer): Version of the callback; send it back on change (409 version_conflict when it is outdated)

Example 200 answer:

```json
{
  "closed": false,
  "contact": {
    "id": "6b8d0f2a-4c6e-4a8b-9d1f-3a5c7e9b1d11",
    "name": "Katrin Stadler"
  },
  "contactName": "Katrin Stadler",
  "createdAt": "2026-11-17T15:20:00Z",
  "createdBy": "sophie.huber@muster-it.example",
  "createdByName": "Sophie Huber",
  "customFields": {},
  "customer": {
    "id": "3c5e7a9c-1d3f-4b5a-9c7e-1a3c5e7a9c11",
    "name": "Alpenhotel Seeblick GmbH \u0026 Co. KG"
  },
  "desiredAt": "2026-11-19T08:00:00Z",
  "desiredHasTime": true,
  "doneNote": "",
  "id": "7b4c5d6e-8f9a-4b0c-9d2e-4f5a6b7c8d01",
  "itemId": "",
  "note": "Frau Stadler möchte kurz zur Kassenanbindung sprechen, bevor die Frühschicht beginnt.",
  "number": 12,
  "origin": "",
  "overdue": false,
  "phone": "+49 8652 987612",
  "reason": "callback_requested",
  "responsibleName": "Elias Gruber",
  "responsibleRef": "elias.gruber@muster-it.example",
  "status": "open",
  "updatedAt": "2026-11-17T15:20:00Z",
  "version": 1
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/desk/v1/callbacks/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/customer-mail' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Idempotency-Key: string' \
  -H 'Content-Type: application/json' \
  --data '{"body":"Guten Tag Frau Stadler,\n\nwir haben heute versucht, Sie zurückzurufen, Sie aber leider nicht erreicht. Wir melden uns morgen wieder.\n\nViele Grüße\nElias Gruber","subject":"Ihr Rückrufwunsch bei Muster IT","version":3}'
```
