## Change name, switch, address and folders of a mailbox at its revision (comms:admin; desk:admin its ticket mailboxes, hr:recruiting:manage its applicant mailboxes; Microsoft 365 mailboxes only comms:admin)

`PUT /api/comms/v1/mailboxes/{id}`

Module: Comms · operationId: `updateMailbox` · Tag: Mailboxes · Auth: access token (`Authorization: Bearer <accessToken>`)

An empty `address` keeps the stored one (kind msgraph); kind and consumer cannot change.

### Parameters

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

### Request body

`application/json` (required)

- `address` (string (email)): Microsoft 365 mailbox the connection reads and answers from (msgraph; required on create, stored lower-case; empty on change keeps it) (max length 254)
- `archiveFolder` (string): Folder processed mail is moved to (msgraph)
- `channelId` (string (uuid)): Microsoft 365 connection (create, msgraph)
- `consumer` (string): Create only; invoice only with kind msgraph (the platform address of the Belegeingang: /mail-intake) (one of `desk`, `recruiting`, `invoice`)
- `enabled` (boolean): Import mails; omitted keeps the value
- `fetchFolder` (string): Folder new mail is read from (msgraph)
- `kind` (string): Create only (one of `ses`, `msgraph`)
- `localPart` (string): Part before the @ (create, ses; required there). a–z, 0–9 and inner hyphens; postmaster, abuse and the like are reserved (max length 40)
- `name` (string): Display name (max length 100)
- `progressFolder` (string): Folder mail is moved to while it is processed (msgraph)
- `randomSuffix` (boolean): Adds a random suffix (support-k7m2qa) so the address cannot be guessed (create, ses)
- `rejectedFolder` (string): Folder rejected mail is moved to (msgraph)
- `rev` (integer): Revision a change is based on (0 creates)

Example:

```json
{
  "address": "support@muster-it.example",
  "archiveFolder": "Posteingang/Erledigt",
  "channelId": "5e7a9c1b-3d4f-4a6b-9c8d-0e1f2a3b4c5d",
  "consumer": "desk",
  "enabled": true,
  "fetchFolder": "Posteingang",
  "kind": "msgraph",
  "name": "Service Desk",
  "progressFolder": "Posteingang/In Bearbeitung",
  "rejectedFolder": "Posteingang/Abgelehnt",
  "rev": 0
}
```

### Responses

- **200** Mailbox (`application/json`)
- **400** Error (`application/json`)
- **403** Error (`application/json`)
- **404** Error (`application/json`)
- **409** Error (`application/json`)

Fields of the 200 answer:

- `address` (string): Platform address (ses) or the Microsoft 365 mailbox address (msgraph)
- `archiveFolder` (string): Folder processed mail is moved to (msgraph)
- `channelId` (string (uuid)): Microsoft 365 connection that reads the mailbox (msgraph)
- `channelName` (string): Name of that connection
- `consumer` (string): The module the mails go to (one of `invoice`, `desk`, `recruiting`)
- `enabled` (boolean): Mails are imported
- `fetchFolder` (string): Folder new mail is read from (msgraph)
- `id` (string (uuid)): Mailbox id
- `kind` (string): ses: a platform address; msgraph: a Microsoft 365 mailbox (one of `ses`, `msgraph`)
- `lastError` (string): Error of the last import run
- `lastImported` (integer): Mails imported by the last run (msgraph) or received in total (ses)
- `lastReceivedAt` (string (date-time)): Time of the last received mail
- `lastRunAt` (string (date-time)): Time of the last import run (msgraph)
- `name` (string): Display name
- `pending` (integer): Received mails still waiting for their consumer (state PENDING)
- `previous` (array of object): Rotated addresses that are still accepted (ses)
  - `address` (string): The old address
  - `validUntil` (string (date-time)): Until when it is accepted
- `progressFolder` (string): Folder mail is moved to while it is processed (msgraph)
- `rejectedFolder` (string): Folder rejected mail is moved to (msgraph)
- `rev` (integer): Revision for optimistic locking (send it back as `rev`)
- `updatedAt` (string (date-time)): Time of the last change
- `updatedBy` (string): Who changed the mailbox last

Example 200 answer:

```json
{
  "address": "support@muster-it.example",
  "archiveFolder": "Posteingang/Erledigt",
  "channelId": "5e7a9c1b-3d4f-4a6b-9c8d-0e1f2a3b4c5d",
  "channelName": "Microsoft 365 Muster IT",
  "consumer": "desk",
  "enabled": true,
  "fetchFolder": "Posteingang",
  "id": "3d5f7a9b-1c2e-4f4a-8b6c-8d0e1f2a3b4c",
  "kind": "msgraph",
  "lastImported": 3,
  "lastReceivedAt": "2026-11-18T07:58:41Z",
  "lastRunAt": "2026-11-18T08:00:03Z",
  "name": "Service Desk",
  "pending": 0,
  "progressFolder": "Posteingang/In Bearbeitung",
  "rejectedFolder": "Posteingang/Abgelehnt",
  "rev": 7,
  "updatedAt": "2026-10-21T15:30:00Z",
  "updatedBy": "sophie.huber@muster-it.example"
}
```

### Example request

```bash
curl -X PUT 'https://api.mbcom.cloud/api/comms/v1/mailboxes/string' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"address":"support@muster-it.example","archiveFolder":"Posteingang/Erledigt","channelId":"5e7a9c1b-3d4f-4a6b-9c8d-0e1f2a3b4c5d","consumer":"desk","enabled":true,"fetchFolder":"Posteingang","kind":"msgraph","name":"Service Desk","progressFolder":"Posteingang/In Bearbeitung","rejectedFolder":"Posteingang/Abgelehnt","rev":0}'
```
