## Change a mail source; needs the current version, the mailbox cannot change (desk:admin)

`PUT /api/desk/v1/mail-sources/{id}`

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

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Request body

`application/json` (required)

- `defaultSpaceId` (string, required): Space of tickets no route matched
- `mailboxId` (string, required): Mailbox id in comms
- `aiRouting` (object): When no route matches, the AI chooses the space of a new ticket among the candidates (described in the admin's words); below the threshold, or when nothing fits, the default space is used.
  - `candidates` (array of object): Spaces the AI may choose
    - `description` (string, required): What belongs in the space, in the admin's words (max length 500)
    - `spaceId` (string, required): Space the AI may choose
    - `typeId` (string): Type of tickets created there
  - `enabled` (boolean): The AI chooses the space when no route matched
  - `threshold` (number): Default 0.7 (max 1)
- `defaultTypeId` (string, nullable): Empty uses the space''s default type
- `enabled` (boolean): Whether the mailbox feeds desk
- `id` (string, read-only): Id of the mail source
- `name` (string): Name of the mail source
- `replyEnabled` (boolean): Agents may answer by mail through this mailbox
- `routes` (array of object): Routes in order; the first matching one decides space and type
  - `condition` (string, required): When the route takes a mail: a bool expression in the flow language over `trigger.data`, the facts of the received mail (`from`, `fromDomain`, `to`, `subject`, `body`, `hasAttachments`, `mailbox`; `GET /conditions/catalog`, `mail`). Required. One that cannot be evaluated for a mail does not hold (the next route, at last the default space). (max length 4000)
  - `spaceId` (string, required): Space of the route's tickets
  - `name` (string): Name of the route
  - `typeId` (string): Type of the route's tickets (default: the space's)
- `updatedAt` (string (date-time), read-only): When it was last changed
- `updatedBy` (string, read-only): Login (e-mail) of who last changed it
- `version` (integer): Version of the mail source; send it back on change

Example:

```json
{
  "aiRouting": {
    "candidates": [],
    "enabled": false,
    "threshold": 0.8
  },
  "defaultSpaceId": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c00",
  "defaultTypeId": "5d2e3f4a-6b7c-4d8e-9f0a-2b3c4d5e6f02",
  "enabled": true,
  "id": "3f0a1b2c-4d5e-4f6a-9b8c-0d1e2f3a4b11",
  "mailboxId": "3f0a1b2c-4d5e-4f6a-9b8c-0d1e2f3a4b01",
  "name": "support@muster-it.example",
  "replyEnabled": true,
  "routes": [
    {
      "condition": "trigger.data.subject contains \"Störung\" || trigger.data.subject contains \"geht nicht\"",
      "name": "Störungsmeldungen",
      "spaceId": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c00",
      "typeId": "5d2e3f4a-6b7c-4d8e-9f0a-2b3c4d5e6f01"
    }
  ],
  "updatedAt": "2026-10-20T13:40:00Z",
  "updatedBy": "elias.gruber@muster-it.example",
  "version": 3
}
```

### Responses

- **200** Saved (`application/json`)
- **409** Version conflict

Fields of the 200 answer:

- `defaultSpaceId` (string, required): Space of tickets no route matched
- `mailboxId` (string, required): Mailbox id in comms
- `aiRouting` (object): When no route matches, the AI chooses the space of a new ticket among the candidates (described in the admin's words); below the threshold, or when nothing fits, the default space is used.
  - `candidates` (array of object): Spaces the AI may choose
    - `description` (string, required): What belongs in the space, in the admin's words (max length 500)
    - `spaceId` (string, required): Space the AI may choose
    - `typeId` (string): Type of tickets created there
  - `enabled` (boolean): The AI chooses the space when no route matched
  - `threshold` (number): Default 0.7 (max 1)
- `defaultTypeId` (string, nullable): Empty uses the space''s default type
- `enabled` (boolean): Whether the mailbox feeds desk
- `id` (string, read-only): Id of the mail source
- `name` (string): Name of the mail source
- `replyEnabled` (boolean): Agents may answer by mail through this mailbox
- `routes` (array of object): Routes in order; the first matching one decides space and type
  - `condition` (string, required): When the route takes a mail: a bool expression in the flow language over `trigger.data`, the facts of the received mail (`from`, `fromDomain`, `to`, `subject`, `body`, `hasAttachments`, `mailbox`; `GET /conditions/catalog`, `mail`). Required. One that cannot be evaluated for a mail does not hold (the next route, at last the default space). (max length 4000)
  - `spaceId` (string, required): Space of the route's tickets
  - `name` (string): Name of the route
  - `typeId` (string): Type of the route's tickets (default: the space's)
- `updatedAt` (string (date-time), read-only): When it was last changed
- `updatedBy` (string, read-only): Login (e-mail) of who last changed it
- `version` (integer): Version of the mail source; send it back on change

Example 200 answer:

```json
{
  "aiRouting": {
    "candidates": [],
    "enabled": false,
    "threshold": 0.8
  },
  "defaultSpaceId": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c00",
  "defaultTypeId": "5d2e3f4a-6b7c-4d8e-9f0a-2b3c4d5e6f02",
  "enabled": true,
  "id": "3f0a1b2c-4d5e-4f6a-9b8c-0d1e2f3a4b11",
  "mailboxId": "3f0a1b2c-4d5e-4f6a-9b8c-0d1e2f3a4b01",
  "name": "support@muster-it.example",
  "replyEnabled": true,
  "routes": [
    {
      "condition": "trigger.data.subject contains \"Störung\" || trigger.data.subject contains \"geht nicht\"",
      "name": "Störungsmeldungen",
      "spaceId": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c00",
      "typeId": "5d2e3f4a-6b7c-4d8e-9f0a-2b3c4d5e6f01"
    }
  ],
  "updatedAt": "2026-10-20T13:40:00Z",
  "updatedBy": "elias.gruber@muster-it.example",
  "version": 3
}
```

### Example request

```bash
curl -X PUT 'https://api.mbcom.cloud/api/desk/v1/mail-sources/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"aiRouting":{"candidates":[],"enabled":false,"threshold":0.8},"defaultSpaceId":"9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c00","defaultTypeId":"5d2e3f4a-6b7c-4d8e-9f0a-2b3c4d5e6f02","enabled":true,"id":"3f0a1b2c-4d5e-4f6a-9b8c-0d1e2f3a4b11","mailboxId":"3f0a1b2c-4d5e-4f6a-9b8c-0d1e2f3a4b01","name":"support@muster-it.example","replyEnabled":true,"routes":[{"condition":"trigger.data.subject contains \"Störung\" || trigger.data.subject contains \"geht nicht\"","name":"Störungsmeldungen","spaceId":"9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c00","typeId":"5d2e3f4a-6b7c-4d8e-9f0a-2b3c4d5e6f01"}],"updatedAt":"2026-10-20T13:40:00Z","updatedBy":"elias.gruber@muster-it.example","version":3}'
```
