## Replace the platform address (comms:admin)

`POST /api/comms/v1/mail-intake/rotate`

Module: Comms · operationId: `rotateMailIntake` · Tag: Mailbox import · Auth: access token (`Authorization: Bearer <accessToken>`)

The old address is still accepted for `graceDays` (default 14; 0 stops it at once, e.g. when it leaked). Without
`localPart` the new address keeps the chosen part of the current one with a new random suffix.

### Request body

`application/json` (required)

- `rev` (integer, required): Revision the change is based on
- `graceDays` (integer): Days the old address stays accepted (default 14; 0 stops it at once) (max 90)
- `localPart` (string): Part before the @ of the new address; default the current chosen part (max length 40)
- `randomSuffix` (boolean): Adds a new random suffix (default true)

Example:

```json
{
  "graceDays": 14,
  "randomSuffix": true,
  "rev": 5
}
```

### Responses

- **200** Intake (`application/json`)
- **404** Error (`application/json`)
- **409** Error (`application/json`)

Fields of the 200 answer:

- `address` (string): The current address; empty until the intake was activated
- `available` (boolean): The platform has a mail domain (else the intake cannot be activated)
- `enabled` (boolean): Mail to the address is imported
- `lastImported` (integer): Mails received in total
- `lastReceivedAt` (string (date-time)): Time of the last received mail
- `mailDomain` (string): The tenant's mail domain; empty while the tenant has no subdomain
- `pending` (integer): Received mails still waiting for their consumer (state PENDING)
- `previous` (array of object): Rotated addresses that are still accepted
  - `address` (string): The old address
  - `validUntil` (string (date-time)): Until when it is accepted
- `rev` (integer): Revision for optimistic locking; 0 while the intake is not activated
- `updatedAt` (string (date-time)): Time of the last change
- `updatedBy` (string): Who changed the intake last

Example 200 answer:

```json
{
  "address": "belege-k7m2qa@demo.on.beta.mbcom.dev",
  "available": true,
  "enabled": true,
  "lastImported": 342,
  "lastReceivedAt": "2026-11-18T06:47:12Z",
  "mailDomain": "demo.on.beta.mbcom.dev",
  "pending": 1,
  "previous": [
    {
      "address": "belege-x3p9tz@demo.on.beta.mbcom.dev",
      "validUntil": "2026-11-30T00:00:00Z"
    }
  ],
  "rev": 5,
  "updatedAt": "2026-11-16T10:02:44Z",
  "updatedBy": "christina.adler@muster-it.example"
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/comms/v1/mail-intake/rotate' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"graceDays":14,"randomSuffix":true,"rev":5}'
```
