# ConnectCloud Comms API (v1.0.0)

Outgoing mail and webhooks: channels, templates, the delivery log, inbound webhooks and mailboxes.

Base URLs:

- Production: `https://api.mbcom.cloud/api/comms/v1`
- Staging: `https://api.mbcom.cloud/api/comms/v1`
- Sandbox: `https://developers.mbcom.cloud/sandbox/comms`

comms sends and receives messages for ConnectCloud: e-mail and webhooks today, more channel
kinds (SMTP, Teams, Matrix, ntfy) as providers later. Other modules hand it a **template key
with parameters** – never finished HTML – and comms renders, routes, retries and logs the
message.

## Model
- A **message** is one send intent: template, parameters, route and recipients, unique per
  tenant by its `idempotencyKey`. Content is rendered at send time.
- A **delivery** is one recipient of a message on one channel. Deliveries are queued, sent by
  a worker on every replica, retried with exponential backoff and jitter by the class of the
  message, and end as `sent`, `dead`, `suppressed`, `expired` or `cancelled`.
- A **channel** is a configured provider (Amazon SES platform mail, a tenant's Microsoft 365
  connection – an Entra app registration whose mailboxes are set up under /mailboxes –, a webhook). Secrets are
  encrypted at rest and never returned. A tenant default route falls back to the platform channel while the tenant
  has no default e-mail channel that can send (a Microsoft 365 connection only with `senderAddress`).
- The **class** of a message comes from its template: `action_link` mails (invitations,
  recovery, restore) never go to distribution addresses, and their parameters are deleted once
  every delivery is final.
- The **platform scope** `_platform/_platform` owns MBCOM's own mails and contact lists. It is
  never visible through tenant APIs.

## Authentication
Send an access token as `Authorization: Bearer <accessToken>`. Get it by exchanging an API key at
`POST https://api.mbcom.cloud/api/hr/v1/auth/token`; it lives 15 minutes and carries the key's permissions.
The tenant is always the one of the token. Guide: https://developers.mbcom.cloud/guides/authentication

## Permissions
| Permission | Grants |
|---|---|
| `comms:read` | delivery log, received webhooks |
| `comms:admin` | channels, inbound webhooks, retrying deliveries |

## Conventions
- Errors have the shape `{error, code, field?}`. `422` answers are permanent rejections
  (`unknown_template`, `invalid_params`, `invalid_recipient`, `distribution_forbidden`,
  `no_channel`, `channel_unavailable`) – a dispatcher must not retry them.
- Rate limits on tenant routes: 20 requests per second per client and route with bursts up
  to 100.

# Settings

## Channel kinds and settings for the settings pages (comms:read)

`GET /api/comms/v1/bootstrap`

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

### Responses

- **200** Bootstrap (`application/json`)
- **403** Error (`application/json`)

Fields of the 200 answer:

- `canAdmin` (boolean): Whether the caller may change channels and settings (comms:admin)
- `channelKinds` (array of ChannelKind): The channel kinds a tenant can configure, with their form fields
  - `capabilities` (object): Optional abilities of the kind
    - `html` (boolean): The kind can send HTML
    - `inbound` (boolean): The kind can also receive (a mailbox)
  - `description` (string): Short explanation of the kind
  - `fields` (array of FieldSpec): Configuration and secret fields of the kind
    - `help` (string): Help text for the field
    - `key` (string): Key in `config` or `secrets`
    - `label` (string): Display label of the field
    - `options` (array of object): Choices of a select field
      - `label` (string): Display label
      - `value` (string): Stored value
    - `required` (boolean): The field must be set
    - `secret` (boolean): Stored encrypted and never returned
    - `type` (string): Input type; secret fields go into `secrets` and are never returned (one of `text`, `email`, `url`, `secret`, `select`, `number`, `bool`)
  - `kind` (string): Kind key, used as `kind` when creating a channel
  - `label` (string): Display name of the kind
  - `managed` (boolean): Created by comms itself (kind `teams`: when the Teams app is added to a team or group chat), never through POST /channels; the configuration is read-only
  - `medium` (string): push is the platform channel that fans out to the devices of a person (ADR 0043); no caller routes to it (one of `email`, `webhook`, `teams`, `push`)
  - `owner` (string): platform: run by the platform; tenant: configured by the tenant (one of `platform`, `tenant`)
- `events` (array of EventSpec): The event catalogue personal subscriptions can start on
  - `default` (object): Default subject and body of a notification of the event
    - `body` (string): Body template
    - `subject` (string): Subject template
  - `fields` (array of EventField): Payload fields conditions and templates may use
    - `kind` (string): Value type of the field (one of `text`, `number`, `date`, `bool`, `list`)
    - `label` (string): Display name of the field
    - `path` (string): Path of the field in the event payload
  - `group` (string): Group the event is listed under
  - `label` (string): Display name of the event
  - `link` (string): Portal path of the event's record with {path} placeholders
  - `people` (array of object): Payload fields that name people (recipients of the event)
    - `kind` (string): How the field names the person (one of `email`, `employee`, `user_ref`, `user_refs`)
    - `label` (string): Display name of the role
    - `manager` (boolean): The person's managers can be addressed too
    - `path` (string): Path of the field in the event payload
  - `source` (string): Producing module
  - `type` (string): Event type, e.g. hr.absence.requested
- `settings` (Settings)
  - `defaultEmailChannelId` (string (uuid)): The tenant's default e-mail channel; empty: the platform channel
  - `rev` (integer): Revision of the settings

Example 200 answer:

```json
{
  "canAdmin": true,
  "channelKinds": [
    {
      "capabilities": {
        "html": false,
        "inbound": false
      },
      "description": "Signierte HTTP-Anfragen an eine Adresse Ihrer Wahl, z. B. einen Teams-Workflow oder Power Automate.",
      "fields": [
        {
          "help": "Wird verschlüsselt gespeichert, weil Webhook-Adressen oft ein Zugriffstoken enthalten.",
          "key": "url",
          "label": "Adresse (URL)",
          "required": true,
          "secret": true,
          "type": "url"
        },
        {
          "key": "format",
          "label": "Format",
          "options": [
            {
              "label": "JSON-Ereignis",
              "value": "json_event"
            },
            {
              "label": "Microsoft Teams (Adaptive Card)",
              "value": "teams_card"
            }
          ],
          "required": true,
          "secret": false,
          "type": "select"
        }
      ],
      "kind": "webhook",
      "label": "Webhook",
      "managed": false,
      "medium": "webhook",
      "owner": "tenant"
    }
  ],
  "events": [
    {
      "default": {
        "body": "Die Abwesenheit „{{typeName}}“ von {{employeeName}} vom {{startDate}} bis {{endDate}} ({{days}} Arbeitstage) wurde beantragt.\n\n{{link}}",
        "subject": "Abwesenheit beantragt: {{employeeName}} ({{startDate}} – {{endDate}})"
      },
      "fields": [
        {
          "kind": "text",
          "label": "Mitarbeiter:in",
          "path": "employeeName"
        },
        {
          "kind": "date",
          "label": "Von",
          "path": "startDate"
        },
        {
          "kind": "date",
          "label": "Bis",
          "path": "endDate"
        },
        {
          "kind": "number",
          "label": "Arbeitstage",
          "path": "days"
        }
      ],
      "group": "Personal",
      "label": "Abwesenheit beantragt",
      "link": "/hr/absences/{absenceId}",
      "people": [
        {
          "kind": "employee",
          "label": "Antragsteller:in",
          "manager": true,
          "path": "employeeId"
        }
      ],
      "source": "hr",
      "type": "hr.absence.requested"
    }
  ],
  "settings": {
    "defaultEmailChannelId": "6b1f3c2a-8d4e-4f5a-9b7c-1e2d3f4a5b6c",
    "rev": 3
  }
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/comms/v1/bootstrap' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Tenant settings (comms:read)

`GET /api/comms/v1/settings`

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

### Responses

- **200** Settings (`application/json`)

Fields of the 200 answer:

- `defaultEmailChannelId` (string (uuid)): The tenant's default e-mail channel; empty: the platform channel
- `rev` (integer): Revision of the settings

Example 200 answer:

```json
{
  "defaultEmailChannelId": "6b1f3c2a-8d4e-4f5a-9b7c-1e2d3f4a5b6c",
  "rev": 3
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/comms/v1/settings' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Change the default e-mail channel (comms:admin)

`PUT /api/comms/v1/settings`

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

### Request body

`application/json` (required)

- `defaultEmailChannelId` (string (uuid)): The tenant's default e-mail channel; empty: the platform channel
- `rev` (integer): Revision of the settings

Example:

```json
{
  "defaultEmailChannelId": "6b1f3c2a-8d4e-4f5a-9b7c-1e2d3f4a5b6c",
  "rev": 3
}
```

### Responses

- **200** Settings (`application/json`)
- **400** Error (`application/json`)
- **409** Error (`application/json`)

Fields of the 200 answer:

- `defaultEmailChannelId` (string (uuid)): The tenant's default e-mail channel; empty: the platform channel
- `rev` (integer): Revision of the settings

Example 200 answer:

```json
{
  "defaultEmailChannelId": "6b1f3c2a-8d4e-4f5a-9b7c-1e2d3f4a5b6c",
  "rev": 3
}
```

### Example request

```bash
curl -X PUT 'https://api.mbcom.cloud/api/comms/v1/settings' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"defaultEmailChannelId":"6b1f3c2a-8d4e-4f5a-9b7c-1e2d3f4a5b6c","rev":3}'
```

# Channels

## Channels of the tenant (comms:read)

`GET /api/comms/v1/channels`

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

### Responses

- **200** Channels (`application/json`)

Fields of the 200 answer:

- `items` (array of Channel): The tenant's channels
  - `config` (object): The kind's public configuration. Kind `teams` (read-only): `teamName`, `channelName` and `conversationType` (`channel` or `groupChat`); the conversation's Teams ids stay in comms.
  - `createdAt` (string (date-time)): Creation time
  - `createdBy` (string): Who created the channel
  - `id` (string (uuid)): Channel id
  - `isDefault` (boolean): The tenant's default e-mail channel
  - `kind` (string): Channel kind (see ChannelKind.kind)
  - `lastCheckAt` (string (date-time)): Time of the last connection test
  - `lastCheckOk` (boolean): Result of the last connection test
  - `lastError` (string): Error of the last connection test
  - `medium` (string): push is the platform channel that fans out to the devices of a person (ADR 0043); no caller routes to it (one of `email`, `webhook`, `teams`, `push`)
  - `name` (string): Display name
  - `rev` (integer): Revision for optimistic locking (send it back as `rev`)
  - `secrets` (object): Which secret fields are set; values are never returned
  - `status` (string): active channels send; disabled ones do not (one of `active`, `disabled`)
  - `updatedAt` (string (date-time)): Time of the last change

Example 200 answer:

```json
{
  "items": [
    {
      "config": {
        "format": "teams_card"
      },
      "createdAt": "2026-09-03T14:05:11Z",
      "createdBy": "sophie.huber@muster-it.example",
      "id": "9c4e2b7a-1d3f-4a6b-8c5d-2e7f9a1b3c4d",
      "isDefault": false,
      "kind": "webhook",
      "lastCheckAt": "2026-11-16T08:12:40Z",
      "lastCheckOk": true,
      "medium": "webhook",
      "name": "Teams-Kanal Service Desk",
      "rev": 2,
      "secrets": {
        "signingSecret": true,
        "url": true
      },
      "status": "active",
      "updatedAt": "2026-11-16T08:12:40Z"
    }
  ]
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/comms/v1/channels' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Create a channel (comms:admin)

`POST /api/comms/v1/channels`

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

The first e-mail channel becomes the tenant's default. At most 20 channels per tenant. Channels of kind `teams`
are created by comms when the Teams app is added to a team or group chat (disabled until an administrator
enables them); this route refuses the kind (400).

### Request body

`application/json` (required)

- `config` (object): The kind's configuration fields (FieldSpec keys that are not secret)
- `kind` (string): Only on create
- `name` (string): Display name (max length 80)
- `rev` (integer): Optimistic lock (0 skips the check)
- `secrets` (object): The kind's secret fields; empty or ******** keeps the stored value
- `status` (string): active or disabled (one of `active`, `disabled`)

Example:

```json
{
  "config": {
    "format": "teams_card"
  },
  "kind": "webhook",
  "name": "Teams-Kanal Service Desk",
  "rev": 0,
  "secrets": {
    "url": "https://muster-it.webhook.office.example/workflows/servicedesk"
  },
  "status": "active"
}
```

### Responses

- **201** Created (`application/json`)
- **400** Error (`application/json`)

Fields of the 201 answer:

- `config` (object): The kind's public configuration. Kind `teams` (read-only): `teamName`, `channelName` and `conversationType` (`channel` or `groupChat`); the conversation's Teams ids stay in comms.
- `createdAt` (string (date-time)): Creation time
- `createdBy` (string): Who created the channel
- `id` (string (uuid)): Channel id
- `isDefault` (boolean): The tenant's default e-mail channel
- `kind` (string): Channel kind (see ChannelKind.kind)
- `lastCheckAt` (string (date-time)): Time of the last connection test
- `lastCheckOk` (boolean): Result of the last connection test
- `lastError` (string): Error of the last connection test
- `medium` (string): push is the platform channel that fans out to the devices of a person (ADR 0043); no caller routes to it (one of `email`, `webhook`, `teams`, `push`)
- `name` (string): Display name
- `rev` (integer): Revision for optimistic locking (send it back as `rev`)
- `secrets` (object): Which secret fields are set; values are never returned
- `status` (string): active channels send; disabled ones do not (one of `active`, `disabled`)
- `updatedAt` (string (date-time)): Time of the last change

Example 201 answer:

```json
{
  "config": {
    "format": "teams_card"
  },
  "createdAt": "2026-09-03T14:05:11Z",
  "createdBy": "sophie.huber@muster-it.example",
  "id": "9c4e2b7a-1d3f-4a6b-8c5d-2e7f9a1b3c4d",
  "isDefault": false,
  "kind": "webhook",
  "lastCheckAt": "2026-11-16T08:12:40Z",
  "lastCheckOk": true,
  "medium": "webhook",
  "name": "Teams-Kanal Service Desk",
  "rev": 2,
  "secrets": {
    "signingSecret": true,
    "url": true
  },
  "status": "active",
  "updatedAt": "2026-11-16T08:12:40Z"
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/comms/v1/channels' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"config":{"format":"teams_card"},"kind":"webhook","name":"Teams-Kanal Service Desk","rev":0,"secrets":{"url":"https://muster-it.webhook.office.example/workflows/servicedesk"},"status":"active"}'
```

## One channel (comms:read)

`GET /api/comms/v1/channels/{id}`

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

### Parameters

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

### Responses

- **200** Channel (`application/json`)
- **404** Error (`application/json`)

Fields of the 200 answer:

- `config` (object): The kind's public configuration. Kind `teams` (read-only): `teamName`, `channelName` and `conversationType` (`channel` or `groupChat`); the conversation's Teams ids stay in comms.
- `createdAt` (string (date-time)): Creation time
- `createdBy` (string): Who created the channel
- `id` (string (uuid)): Channel id
- `isDefault` (boolean): The tenant's default e-mail channel
- `kind` (string): Channel kind (see ChannelKind.kind)
- `lastCheckAt` (string (date-time)): Time of the last connection test
- `lastCheckOk` (boolean): Result of the last connection test
- `lastError` (string): Error of the last connection test
- `medium` (string): push is the platform channel that fans out to the devices of a person (ADR 0043); no caller routes to it (one of `email`, `webhook`, `teams`, `push`)
- `name` (string): Display name
- `rev` (integer): Revision for optimistic locking (send it back as `rev`)
- `secrets` (object): Which secret fields are set; values are never returned
- `status` (string): active channels send; disabled ones do not (one of `active`, `disabled`)
- `updatedAt` (string (date-time)): Time of the last change

Example 200 answer:

```json
{
  "config": {
    "format": "teams_card"
  },
  "createdAt": "2026-09-03T14:05:11Z",
  "createdBy": "sophie.huber@muster-it.example",
  "id": "9c4e2b7a-1d3f-4a6b-8c5d-2e7f9a1b3c4d",
  "isDefault": false,
  "kind": "webhook",
  "lastCheckAt": "2026-11-16T08:12:40Z",
  "lastCheckOk": true,
  "medium": "webhook",
  "name": "Teams-Kanal Service Desk",
  "rev": 2,
  "secrets": {
    "signingSecret": true,
    "url": true
  },
  "status": "active",
  "updatedAt": "2026-11-16T08:12:40Z"
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/comms/v1/channels/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Delete a channel (comms:admin)

`DELETE /api/comms/v1/channels/{id}`

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

The channel is hidden; its deliveries stay in the log.

### Parameters

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

### Responses

- **204** Deleted
- **404** Error (`application/json`)

### Example request

```bash
curl -X DELETE 'https://api.mbcom.cloud/api/comms/v1/channels/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Change a channel (comms:admin)

`PATCH /api/comms/v1/channels/{id}`

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

Empty fields keep their value; secrets sent empty or as `********` keep the stored secret.

### Parameters

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

### Request body

`application/json` (required)

- `config` (object): The kind's configuration fields (FieldSpec keys that are not secret)
- `kind` (string): Only on create
- `name` (string): Display name (max length 80)
- `rev` (integer): Optimistic lock (0 skips the check)
- `secrets` (object): The kind's secret fields; empty or ******** keeps the stored value
- `status` (string): active or disabled (one of `active`, `disabled`)

Example:

```json
{
  "config": {
    "format": "teams_card"
  },
  "kind": "webhook",
  "name": "Teams-Kanal Service Desk",
  "rev": 0,
  "secrets": {
    "url": "https://muster-it.webhook.office.example/workflows/servicedesk"
  },
  "status": "active"
}
```

### Responses

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

Fields of the 200 answer:

- `config` (object): The kind's public configuration. Kind `teams` (read-only): `teamName`, `channelName` and `conversationType` (`channel` or `groupChat`); the conversation's Teams ids stay in comms.
- `createdAt` (string (date-time)): Creation time
- `createdBy` (string): Who created the channel
- `id` (string (uuid)): Channel id
- `isDefault` (boolean): The tenant's default e-mail channel
- `kind` (string): Channel kind (see ChannelKind.kind)
- `lastCheckAt` (string (date-time)): Time of the last connection test
- `lastCheckOk` (boolean): Result of the last connection test
- `lastError` (string): Error of the last connection test
- `medium` (string): push is the platform channel that fans out to the devices of a person (ADR 0043); no caller routes to it (one of `email`, `webhook`, `teams`, `push`)
- `name` (string): Display name
- `rev` (integer): Revision for optimistic locking (send it back as `rev`)
- `secrets` (object): Which secret fields are set; values are never returned
- `status` (string): active channels send; disabled ones do not (one of `active`, `disabled`)
- `updatedAt` (string (date-time)): Time of the last change

Example 200 answer:

```json
{
  "config": {
    "format": "teams_card"
  },
  "createdAt": "2026-09-03T14:05:11Z",
  "createdBy": "sophie.huber@muster-it.example",
  "id": "9c4e2b7a-1d3f-4a6b-8c5d-2e7f9a1b3c4d",
  "isDefault": false,
  "kind": "webhook",
  "lastCheckAt": "2026-11-16T08:12:40Z",
  "lastCheckOk": true,
  "medium": "webhook",
  "name": "Teams-Kanal Service Desk",
  "rev": 2,
  "secrets": {
    "signingSecret": true,
    "url": true
  },
  "status": "active",
  "updatedAt": "2026-11-16T08:12:40Z"
}
```

### Example request

```bash
curl -X PATCH 'https://api.mbcom.cloud/api/comms/v1/channels/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"config":{"format":"teams_card"},"kind":"webhook","name":"Teams-Kanal Service Desk","rev":0,"secrets":{"url":"https://muster-it.webhook.office.example/workflows/servicedesk"},"status":"active"}'
```

## Test the connection of a channel (comms:admin)

`POST /api/comms/v1/channels/{id}/test`

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

### Parameters

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

### Responses

- **200** Result (`application/json`)
- **404** Error (`application/json`)

Fields of the 200 answer:

- `checkedAt` (string (date-time)): Time of the test
- `checks` (array of object): The single checks of the test
  - `message` (string): Detail of the result
  - `name` (string): Name of the check
  - `ok` (boolean): The check passed
- `ok` (boolean): All checks passed

Example 200 answer:

```json
{
  "checkedAt": "2026-11-16T08:12:40Z",
  "checks": [
    {
      "message": "Die Adresse ist erreichbar und öffentlich.",
      "name": "Adresse",
      "ok": true
    },
    {
      "message": "Antwort 202 Accepted in 412 ms.",
      "name": "Testnachricht",
      "ok": true
    }
  ],
  "ok": true
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/comms/v1/channels/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/test' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

# Delivery log

## The tenant's delivery log, newest first (comms:read)

`GET /api/comms/v1/deliveries`

Module: Comms · operationId: `listDeliveries` · Tag: Delivery log · Auth: access token (`Authorization: Bearer <accessToken>`)

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `status` | query | string |  | Comma-separated statuses |
| `channelId` | query | string |  |  |
| `subscriptionId` | query | string |  | Deliveries a personal subscription sent |
| `origin` | query | string |  | api: submitted by a module or the API (flows' mail too); job: bulk mail and digests; test: a test send; subscription: a personal subscription; event_push: the default push of an event (one of `api`, `job`, `test`, `subscription`, `event_push`) |
| `q` | query | string |  | Recipient or subject |
| `limit` | query | integer |  | 1–200; anything else is 400 invalid (default `50`; max 200) |
| `offset` | query | integer |  | 0–10000; anything else is 400 invalid (default `0`; max 10000) |

### Responses

- **200** Page (`application/json`)

Fields of the 200 answer:

- `items` (array of DeliveryRow): Deliveries of the page
  - `attempts` (integer): Number of send attempts so far
  - `channelId` (string (uuid)): Channel the delivery is sent on
  - `channelName` (string): Name of the channel
  - `createdAt` (string (date-time)): Creation time
  - `feedback` (string): What the provider (Amazon SES) reported after accepting the mail; a hard bounce or complaint also suppresses the address (one of `delivered`, `delay`, `bounced`, `complaint`)
  - `feedbackAt` (string (date-time)): When the provider's feedback arrived
  - `feedbackDetail` (string): Detail of the provider's feedback (e.g. the bounce reason)
  - `id` (string (uuid)): Delivery id
  - `lastError` (string): Error message of the last failed attempt
  - `lastErrorCode` (string): Error code of the last failed attempt
  - `medium` (string): Medium of the channel (email, webhook, teams, push)
  - `messageId` (string (uuid)): The message the delivery belongs to
  - `nextAttemptAt` (string (date-time)): When the next attempt is due
  - `origin` (string): api, job, test, subscription or event_push
  - `recipient` (string): Recipient address or webhook target
  - `recipientKind` (string): person, distribution (a shared mailbox) or channel (a webhook)
  - `recipientName` (string): Display name of the recipient
  - `sentAt` (string (date-time)): When the provider accepted the delivery
  - `status` (string): held waits for the recipient's digest or the end of an absence; bundled was sent inside a digest; suppressed with code opted_out was switched off by the recipient (one of `queued`, `sending`, `retry`, `sent`, `dead`, `suppressed`, `expired`, `cancelled`, `held`, `bundled`)
  - `subject` (string): Rendered subject
  - `subscriptionId` (string): The personal subscription the message was sent for (origin subscription)
  - `subscriptionName` (string): Its name while it exists
  - `template` (string): Template key of the message
  - `updatedAt` (string (date-time)): Time of the last change
- `total` (integer): Number of matching deliveries

Example 200 answer:

```json
{
  "items": [
    {
      "attempts": 1,
      "channelId": "6b1f3c2a-8d4e-4f5a-9b7c-1e2d3f4a5b6c",
      "channelName": "Plattform-E-Mail",
      "createdAt": "2026-11-17T09:41:05Z",
      "feedback": "delivered",
      "feedbackAt": "2026-11-17T09:41:09Z",
      "id": "2f8a6c1e-4b3d-4e5f-a7b9-0c1d2e3f4a5b",
      "medium": "email",
      "messageId": "7d3e9f1a-2b4c-4d5e-8f6a-9b0c1d2e3f4a",
      "origin": "api",
      "recipient": "lena.vogel@muster-it.example",
      "recipientKind": "person",
      "recipientName": "Lena Vogel",
      "sentAt": "2026-11-17T09:41:07Z",
      "status": "sent",
      "subject": "Abwesenheit genehmigt: Lena Vogel (23.12.2026 – 02.01.2027)",
      "template": "hr.absence.approved",
      "updatedAt": "2026-11-17T09:41:09Z"
    },
    {
      "attempts": 2,
      "channelId": "9c4e2b7a-1d3f-4a6b-8c5d-2e7f9a1b3c4d",
      "channelName": "Teams-Kanal Service Desk",
      "createdAt": "2026-11-17T09:40:12Z",
      "id": "5b9c1d3e-7f2a-4b4c-8d6e-1a2b3c4d5e6f",
      "lastError": "Der Empfänger antwortete mit 503 Service Unavailable.",
      "lastErrorCode": "http_503",
      "medium": "webhook",
      "messageId": "0e4f6a8b-2c3d-4e5f-9a7b-3c4d5e6f7a8b",
      "nextAttemptAt": "2026-11-17T09:45:00Z",
      "origin": "api",
      "recipient": "Teams-Kanal Service Desk",
      "recipientKind": "channel",
      "recipientName": "Teams-Kanal Service Desk",
      "status": "retry",
      "subject": "Neues Ticket SUP-214: Drucker im Sekretariat druckt nicht",
      "template": "desk.item.created",
      "updatedAt": "2026-11-17T09:42:30Z"
    }
  ],
  "total": 2
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/comms/v1/deliveries' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## A delivery with its attempts (comms:read)

`GET /api/comms/v1/deliveries/{id}`

Module: Comms · operationId: `getDelivery` · Tag: Delivery log · Auth: access token (`Authorization: Bearer <accessToken>`)

### Parameters

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

### Responses

- **200** Delivery (`application/json`)
- **404** Error (`application/json`)

Fields of the 200 answer:

- `attempts` (integer): Number of send attempts so far
- `channelId` (string (uuid)): Channel the delivery is sent on
- `channelName` (string): Name of the channel
- `createdAt` (string (date-time)): Creation time
- `feedback` (string): What the provider (Amazon SES) reported after accepting the mail; a hard bounce or complaint also suppresses the address (one of `delivered`, `delay`, `bounced`, `complaint`)
- `feedbackAt` (string (date-time)): When the provider's feedback arrived
- `feedbackDetail` (string): Detail of the provider's feedback (e.g. the bounce reason)
- `id` (string (uuid)): Delivery id
- `lastError` (string): Error message of the last failed attempt
- `lastErrorCode` (string): Error code of the last failed attempt
- `medium` (string): Medium of the channel (email, webhook, teams, push)
- `messageId` (string (uuid)): The message the delivery belongs to
- `nextAttemptAt` (string (date-time)): When the next attempt is due
- `origin` (string): api, job, test, subscription or event_push
- `recipient` (string): Recipient address or webhook target
- `recipientKind` (string): person, distribution (a shared mailbox) or channel (a webhook)
- `recipientName` (string): Display name of the recipient
- `sentAt` (string (date-time)): When the provider accepted the delivery
- `status` (string): held waits for the recipient's digest or the end of an absence; bundled was sent inside a digest; suppressed with code opted_out was switched off by the recipient (one of `queued`, `sending`, `retry`, `sent`, `dead`, `suppressed`, `expired`, `cancelled`, `held`, `bundled`)
- `subject` (string): Rendered subject
- `subscriptionId` (string): The personal subscription the message was sent for (origin subscription)
- `subscriptionName` (string): Its name while it exists
- `template` (string): Template key of the message
- `updatedAt` (string (date-time)): Time of the last change
- `attemptLog` (array of object): The recorded send attempts
  - `attempt` (integer): Number of the attempt, from 1
  - `durationMs` (integer): Duration in milliseconds
  - `error` (string): Error message of a failed attempt
  - `errorCode` (string): Error code of a failed attempt
  - `httpStatus` (integer): HTTP status the provider answered
  - `outcome` (string): Result of the attempt (one of `sent`, `transient`, `rate_limited`, `permanent`, `misconfigured`)
  - `startedAt` (string (date-time)): Start of the attempt
- `correlationId` (string): Correlation id the sender passed with the message
- `expiresAt` (string (date-time)): After this time the message is no longer sent
- `purged` (boolean): The message content was removed (action links)

Example 200 answer:

```json
{
  "attemptLog": [
    {
      "attempt": 1,
      "durationMs": 384,
      "outcome": "sent",
      "startedAt": "2026-11-17T09:41:06Z"
    }
  ],
  "attempts": 1,
  "channelId": "6b1f3c2a-8d4e-4f5a-9b7c-1e2d3f4a5b6c",
  "channelName": "Plattform-E-Mail",
  "correlationId": "hr.absence:5a1c7e3b-9d2f-4b6a-8e4c-3f1a2b9c7d6e",
  "createdAt": "2026-11-17T09:41:05Z",
  "expiresAt": "2026-11-20T09:41:05Z",
  "feedback": "delivered",
  "feedbackAt": "2026-11-17T09:41:09Z",
  "id": "2f8a6c1e-4b3d-4e5f-a7b9-0c1d2e3f4a5b",
  "medium": "email",
  "messageId": "7d3e9f1a-2b4c-4d5e-8f6a-9b0c1d2e3f4a",
  "origin": "api",
  "purged": false,
  "recipient": "lena.vogel@muster-it.example",
  "recipientKind": "person",
  "recipientName": "Lena Vogel",
  "sentAt": "2026-11-17T09:41:07Z",
  "status": "sent",
  "subject": "Abwesenheit genehmigt: Lena Vogel (23.12.2026 – 02.01.2027)",
  "template": "hr.absence.approved",
  "updatedAt": "2026-11-17T09:41:09Z"
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/comms/v1/deliveries/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Queue a failed delivery again (comms:admin)

`POST /api/comms/v1/deliveries/{id}/retry`

Module: Comms · operationId: `retryDelivery` · Tag: Delivery log · Auth: access token (`Authorization: Bearer <accessToken>`)

Only `dead` deliveries whose message still has its content and has not expired.

### Parameters

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

### Responses

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

Fields of the 200 answer:

- `attempts` (integer): Number of send attempts so far
- `channelId` (string (uuid)): Channel the delivery is sent on
- `channelName` (string): Name of the channel
- `createdAt` (string (date-time)): Creation time
- `feedback` (string): What the provider (Amazon SES) reported after accepting the mail; a hard bounce or complaint also suppresses the address (one of `delivered`, `delay`, `bounced`, `complaint`)
- `feedbackAt` (string (date-time)): When the provider's feedback arrived
- `feedbackDetail` (string): Detail of the provider's feedback (e.g. the bounce reason)
- `id` (string (uuid)): Delivery id
- `lastError` (string): Error message of the last failed attempt
- `lastErrorCode` (string): Error code of the last failed attempt
- `medium` (string): Medium of the channel (email, webhook, teams, push)
- `messageId` (string (uuid)): The message the delivery belongs to
- `nextAttemptAt` (string (date-time)): When the next attempt is due
- `origin` (string): api, job, test, subscription or event_push
- `recipient` (string): Recipient address or webhook target
- `recipientKind` (string): person, distribution (a shared mailbox) or channel (a webhook)
- `recipientName` (string): Display name of the recipient
- `sentAt` (string (date-time)): When the provider accepted the delivery
- `status` (string): held waits for the recipient's digest or the end of an absence; bundled was sent inside a digest; suppressed with code opted_out was switched off by the recipient (one of `queued`, `sending`, `retry`, `sent`, `dead`, `suppressed`, `expired`, `cancelled`, `held`, `bundled`)
- `subject` (string): Rendered subject
- `subscriptionId` (string): The personal subscription the message was sent for (origin subscription)
- `subscriptionName` (string): Its name while it exists
- `template` (string): Template key of the message
- `updatedAt` (string (date-time)): Time of the last change
- `attemptLog` (array of object): The recorded send attempts
  - `attempt` (integer): Number of the attempt, from 1
  - `durationMs` (integer): Duration in milliseconds
  - `error` (string): Error message of a failed attempt
  - `errorCode` (string): Error code of a failed attempt
  - `httpStatus` (integer): HTTP status the provider answered
  - `outcome` (string): Result of the attempt (one of `sent`, `transient`, `rate_limited`, `permanent`, `misconfigured`)
  - `startedAt` (string (date-time)): Start of the attempt
- `correlationId` (string): Correlation id the sender passed with the message
- `expiresAt` (string (date-time)): After this time the message is no longer sent
- `purged` (boolean): The message content was removed (action links)

Example 200 answer:

```json
{
  "attemptLog": [
    {
      "attempt": 1,
      "durationMs": 384,
      "outcome": "sent",
      "startedAt": "2026-11-17T09:41:06Z"
    }
  ],
  "attempts": 1,
  "channelId": "6b1f3c2a-8d4e-4f5a-9b7c-1e2d3f4a5b6c",
  "channelName": "Plattform-E-Mail",
  "correlationId": "hr.absence:5a1c7e3b-9d2f-4b6a-8e4c-3f1a2b9c7d6e",
  "createdAt": "2026-11-17T09:41:05Z",
  "expiresAt": "2026-11-20T09:41:05Z",
  "feedback": "delivered",
  "feedbackAt": "2026-11-17T09:41:09Z",
  "id": "2f8a6c1e-4b3d-4e5f-a7b9-0c1d2e3f4a5b",
  "medium": "email",
  "messageId": "7d3e9f1a-2b4c-4d5e-8f6a-9b0c1d2e3f4a",
  "origin": "api",
  "purged": false,
  "recipient": "lena.vogel@muster-it.example",
  "recipientKind": "person",
  "recipientName": "Lena Vogel",
  "sentAt": "2026-11-17T09:41:07Z",
  "status": "sent",
  "subject": "Abwesenheit genehmigt: Lena Vogel (23.12.2026 – 02.01.2027)",
  "template": "hr.absence.approved",
  "updatedAt": "2026-11-17T09:41:09Z"
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/comms/v1/deliveries/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/retry' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Cancel a delivery that is still waiting (comms:admin)

`POST /api/comms/v1/deliveries/{id}/cancel`

Module: Comms · operationId: `cancelDelivery` · Tag: Delivery log · Auth: access token (`Authorization: Bearer <accessToken>`)

### Parameters

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

### Responses

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

Fields of the 200 answer:

- `attempts` (integer): Number of send attempts so far
- `channelId` (string (uuid)): Channel the delivery is sent on
- `channelName` (string): Name of the channel
- `createdAt` (string (date-time)): Creation time
- `feedback` (string): What the provider (Amazon SES) reported after accepting the mail; a hard bounce or complaint also suppresses the address (one of `delivered`, `delay`, `bounced`, `complaint`)
- `feedbackAt` (string (date-time)): When the provider's feedback arrived
- `feedbackDetail` (string): Detail of the provider's feedback (e.g. the bounce reason)
- `id` (string (uuid)): Delivery id
- `lastError` (string): Error message of the last failed attempt
- `lastErrorCode` (string): Error code of the last failed attempt
- `medium` (string): Medium of the channel (email, webhook, teams, push)
- `messageId` (string (uuid)): The message the delivery belongs to
- `nextAttemptAt` (string (date-time)): When the next attempt is due
- `origin` (string): api, job, test, subscription or event_push
- `recipient` (string): Recipient address or webhook target
- `recipientKind` (string): person, distribution (a shared mailbox) or channel (a webhook)
- `recipientName` (string): Display name of the recipient
- `sentAt` (string (date-time)): When the provider accepted the delivery
- `status` (string): held waits for the recipient's digest or the end of an absence; bundled was sent inside a digest; suppressed with code opted_out was switched off by the recipient (one of `queued`, `sending`, `retry`, `sent`, `dead`, `suppressed`, `expired`, `cancelled`, `held`, `bundled`)
- `subject` (string): Rendered subject
- `subscriptionId` (string): The personal subscription the message was sent for (origin subscription)
- `subscriptionName` (string): Its name while it exists
- `template` (string): Template key of the message
- `updatedAt` (string (date-time)): Time of the last change
- `attemptLog` (array of object): The recorded send attempts
  - `attempt` (integer): Number of the attempt, from 1
  - `durationMs` (integer): Duration in milliseconds
  - `error` (string): Error message of a failed attempt
  - `errorCode` (string): Error code of a failed attempt
  - `httpStatus` (integer): HTTP status the provider answered
  - `outcome` (string): Result of the attempt (one of `sent`, `transient`, `rate_limited`, `permanent`, `misconfigured`)
  - `startedAt` (string (date-time)): Start of the attempt
- `correlationId` (string): Correlation id the sender passed with the message
- `expiresAt` (string (date-time)): After this time the message is no longer sent
- `purged` (boolean): The message content was removed (action links)

Example 200 answer:

```json
{
  "attemptLog": [
    {
      "attempt": 1,
      "durationMs": 384,
      "outcome": "sent",
      "startedAt": "2026-11-17T09:41:06Z"
    }
  ],
  "attempts": 1,
  "channelId": "6b1f3c2a-8d4e-4f5a-9b7c-1e2d3f4a5b6c",
  "channelName": "Plattform-E-Mail",
  "correlationId": "hr.absence:5a1c7e3b-9d2f-4b6a-8e4c-3f1a2b9c7d6e",
  "createdAt": "2026-11-17T09:41:05Z",
  "expiresAt": "2026-11-20T09:41:05Z",
  "feedback": "delivered",
  "feedbackAt": "2026-11-17T09:41:09Z",
  "id": "2f8a6c1e-4b3d-4e5f-a7b9-0c1d2e3f4a5b",
  "medium": "email",
  "messageId": "7d3e9f1a-2b4c-4d5e-8f6a-9b0c1d2e3f4a",
  "origin": "api",
  "purged": false,
  "recipient": "lena.vogel@muster-it.example",
  "recipientKind": "person",
  "recipientName": "Lena Vogel",
  "sentAt": "2026-11-17T09:41:07Z",
  "status": "sent",
  "subject": "Abwesenheit genehmigt: Lena Vogel (23.12.2026 – 02.01.2027)",
  "template": "hr.absence.approved",
  "updatedAt": "2026-11-17T09:41:09Z"
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/comms/v1/deliveries/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/cancel' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

# Inbound webhooks

## Receive a request to an inbound webhook (public)

`POST /api/comms/v1/hooks/{publicId}`

Module: Comms · operationId: `receiveInboundWebhook` · Tag: Inbound webhooks · Auth: none

Needs no session or CSRF token: the endpoint verifies the sender by its scheme
(`standard_webhooks`, `hmac_sha256` or `token`). Only verified requests are stored; a request
with a delivery id seen before is stored once and answered with 200. Unknown or disabled
endpoints answer 404, failed checks 401 without detail. Limited to 10 requests per second per
client with bursts up to 50.

### Parameters

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

### Request body

`*/*` (required)

### Responses

- **200** Already stored (`application/json`)
- **202** Stored (`application/json`)
- **401** Error (`application/json`)
- **404** Error (`application/json`)
- **413** Error (`application/json`)
- **429** Rate limited

Fields of the 200 answer:

- `duplicate` (boolean): The delivery id was seen before; the request was stored once
- `id` (string (uuid)): Id of the stored request

Example 200 answer:

```json
{
  "duplicate": false,
  "id": "4c7d1e9a-3b5f-4a2c-9e8d-6f0a1b2c3d4e"
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/comms/v1/hooks/string' \
  -H 'Content-Type: */*' \
  --data-binary @body
```

## List the tenant's inbound webhooks (comms:read)

`GET /api/comms/v1/inbound-hooks`

Module: Comms · operationId: `listInboundHooks` · Tag: Inbound webhooks · Auth: access token (`Authorization: Bearer <accessToken>`)

### Responses

- **200** Endpoints (`application/json`)

Fields of the 200 answer:

- `items` (array of InboundEndpoint): The tenant's inbound webhooks
  - `config` (InboundConfig): Tunes the scheme to the sender; empty fields take the scheme's usual headers.
    - `idHeader` (string): Header with a unique delivery id; repeated ids are stored once
    - `prefix` (string): Text before the value, e.g. "sha256=" or "Bearer "
    - `signatureHeader` (string): Header with the signature (hmac_sha256) or the token (token)
  - `createdAt` (string (date-time)): Creation time
  - `createdBy` (string): Who created the endpoint
  - `enabled` (boolean): Disabled endpoints answer 404
  - `id` (string (uuid)): Endpoint id
  - `lastReceivedAt` (string (date-time)): Time of the last verified request
  - `lastRejectedAt` (string (date-time)): Time of the last rejected request
  - `lastRejectedReason` (string): Why the last request was rejected
  - `maxBodyBytes` (integer): Largest accepted body in bytes
  - `name` (string): Display name
  - `receivedCount` (integer): Verified requests received
  - `rejectedCount` (integer): Requests rejected by the check
  - `rev` (integer): Revision for optimistic locking (send it back as `rev`)
  - `scheme` (string): How the sender is verified
  - `secret` (string): Only in the answer that created or rotated it
  - `toleranceSecs` (integer): Allowed clock difference for standard_webhooks
  - `url` (string): Public URL the sender posts to

Example 200 answer:

```json
{
  "items": [
    {
      "config": {
        "idHeader": "X-Shop-Delivery",
        "prefix": "sha256=",
        "signatureHeader": "X-Shop-Signature"
      },
      "createdAt": "2026-10-01T10:20:00Z",
      "createdBy": "jonas.bauer@muster-it.example",
      "enabled": true,
      "id": "1a9e5c3b-7d2f-4e6a-b8c4-0d1e2f3a4b5c",
      "lastReceivedAt": "2026-11-18T07:55:32Z",
      "maxBodyBytes": 262144,
      "name": "Shop-Bestellungen",
      "receivedCount": 128,
      "rejectedCount": 2,
      "rev": 4,
      "scheme": "hmac_sha256",
      "toleranceSecs": 300,
      "url": "https://api.mbcom.cloud/api/comms/v1/hooks/f3Kq9ZpL2vXc8RtW1nYb4A"
    }
  ]
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/comms/v1/inbound-hooks' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Create an inbound webhook (comms:admin)

`POST /api/comms/v1/inbound-hooks`

Module: Comms · operationId: `createInboundHook` · Tag: Inbound webhooks · Auth: access token (`Authorization: Bearer <accessToken>`)

The answer carries the secret once; it cannot be read again, only rotated.

### Request body

`application/json` (required)

- `name` (string, required): Display name
- `config` (InboundConfig): Tunes the scheme to the sender; empty fields take the scheme's usual headers.
  - `idHeader` (string): Header with a unique delivery id; repeated ids are stored once
  - `prefix` (string): Text before the value, e.g. "sha256=" or "Bearer "
  - `signatureHeader` (string): Header with the signature (hmac_sha256) or the token (token)
- `enabled` (boolean): Disabled endpoints answer 404; omitted keeps the value (enabled on create)
- `maxBodyBytes` (integer): Largest accepted body (up to 1 MiB)
- `rev` (integer): Revision the change is based on (PATCH)
- `scheme` (string): How the sender is verified (one of `standard_webhooks`, `hmac_sha256`, `token`; default `"standard_webhooks"`)
- `toleranceSecs` (integer): Allowed clock difference for standard_webhooks (30–3600)

Example:

```json
{
  "config": {
    "idHeader": "X-Shop-Delivery",
    "prefix": "sha256=",
    "signatureHeader": "X-Shop-Signature"
  },
  "enabled": true,
  "maxBodyBytes": 262144,
  "name": "Shop-Bestellungen",
  "rev": 0,
  "scheme": "hmac_sha256"
}
```

### Responses

- **201** Endpoint with secret (`application/json`)
- **400** Error (`application/json`)
- **409** Error (`application/json`)

Fields of the 201 answer:

- `config` (InboundConfig): Tunes the scheme to the sender; empty fields take the scheme's usual headers.
  - `idHeader` (string): Header with a unique delivery id; repeated ids are stored once
  - `prefix` (string): Text before the value, e.g. "sha256=" or "Bearer "
  - `signatureHeader` (string): Header with the signature (hmac_sha256) or the token (token)
- `createdAt` (string (date-time)): Creation time
- `createdBy` (string): Who created the endpoint
- `enabled` (boolean): Disabled endpoints answer 404
- `id` (string (uuid)): Endpoint id
- `lastReceivedAt` (string (date-time)): Time of the last verified request
- `lastRejectedAt` (string (date-time)): Time of the last rejected request
- `lastRejectedReason` (string): Why the last request was rejected
- `maxBodyBytes` (integer): Largest accepted body in bytes
- `name` (string): Display name
- `receivedCount` (integer): Verified requests received
- `rejectedCount` (integer): Requests rejected by the check
- `rev` (integer): Revision for optimistic locking (send it back as `rev`)
- `scheme` (string): How the sender is verified
- `secret` (string): Only in the answer that created or rotated it
- `toleranceSecs` (integer): Allowed clock difference for standard_webhooks
- `url` (string): Public URL the sender posts to

Example 201 answer:

```json
{
  "config": {
    "idHeader": "X-Shop-Delivery",
    "prefix": "sha256=",
    "signatureHeader": "X-Shop-Signature"
  },
  "createdAt": "2026-10-01T10:20:00Z",
  "createdBy": "jonas.bauer@muster-it.example",
  "enabled": true,
  "id": "1a9e5c3b-7d2f-4e6a-b8c4-0d1e2f3a4b5c",
  "lastReceivedAt": "2026-11-18T07:55:32Z",
  "lastRejectedAt": "2026-11-02T13:10:04Z",
  "lastRejectedReason": "Signatur ungültig",
  "maxBodyBytes": 262144,
  "name": "Shop-Bestellungen",
  "receivedCount": 128,
  "rejectedCount": 2,
  "rev": 4,
  "scheme": "hmac_sha256",
  "toleranceSecs": 300,
  "url": "https://api.mbcom.cloud/api/comms/v1/hooks/f3Kq9ZpL2vXc8RtW1nYb4A"
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/comms/v1/inbound-hooks' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"config":{"idHeader":"X-Shop-Delivery","prefix":"sha256=","signatureHeader":"X-Shop-Signature"},"enabled":true,"maxBodyBytes":262144,"name":"Shop-Bestellungen","rev":0,"scheme":"hmac_sha256"}'
```

## An inbound webhook (comms:read)

`GET /api/comms/v1/inbound-hooks/{id}`

Module: Comms · operationId: `getInboundHook` · Tag: Inbound webhooks · Auth: access token (`Authorization: Bearer <accessToken>`)

### Parameters

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

### Responses

- **200** Endpoint (`application/json`)
- **404** Error (`application/json`)

Fields of the 200 answer:

- `config` (InboundConfig): Tunes the scheme to the sender; empty fields take the scheme's usual headers.
  - `idHeader` (string): Header with a unique delivery id; repeated ids are stored once
  - `prefix` (string): Text before the value, e.g. "sha256=" or "Bearer "
  - `signatureHeader` (string): Header with the signature (hmac_sha256) or the token (token)
- `createdAt` (string (date-time)): Creation time
- `createdBy` (string): Who created the endpoint
- `enabled` (boolean): Disabled endpoints answer 404
- `id` (string (uuid)): Endpoint id
- `lastReceivedAt` (string (date-time)): Time of the last verified request
- `lastRejectedAt` (string (date-time)): Time of the last rejected request
- `lastRejectedReason` (string): Why the last request was rejected
- `maxBodyBytes` (integer): Largest accepted body in bytes
- `name` (string): Display name
- `receivedCount` (integer): Verified requests received
- `rejectedCount` (integer): Requests rejected by the check
- `rev` (integer): Revision for optimistic locking (send it back as `rev`)
- `scheme` (string): How the sender is verified
- `secret` (string): Only in the answer that created or rotated it
- `toleranceSecs` (integer): Allowed clock difference for standard_webhooks
- `url` (string): Public URL the sender posts to

Example 200 answer:

```json
{
  "config": {
    "idHeader": "X-Shop-Delivery",
    "prefix": "sha256=",
    "signatureHeader": "X-Shop-Signature"
  },
  "createdAt": "2026-10-01T10:20:00Z",
  "createdBy": "jonas.bauer@muster-it.example",
  "enabled": true,
  "id": "1a9e5c3b-7d2f-4e6a-b8c4-0d1e2f3a4b5c",
  "lastReceivedAt": "2026-11-18T07:55:32Z",
  "lastRejectedAt": "2026-11-02T13:10:04Z",
  "lastRejectedReason": "Signatur ungültig",
  "maxBodyBytes": 262144,
  "name": "Shop-Bestellungen",
  "receivedCount": 128,
  "rejectedCount": 2,
  "rev": 4,
  "scheme": "hmac_sha256",
  "toleranceSecs": 300,
  "url": "https://api.mbcom.cloud/api/comms/v1/hooks/f3Kq9ZpL2vXc8RtW1nYb4A"
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/comms/v1/inbound-hooks/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Delete an inbound webhook and its stored requests (comms:admin)

`DELETE /api/comms/v1/inbound-hooks/{id}`

Module: Comms · operationId: `deleteInboundHook` · Tag: Inbound webhooks · Auth: access token (`Authorization: Bearer <accessToken>`)

### Parameters

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

### Responses

- **204** Deleted
- **404** Error (`application/json`)

### Example request

```bash
curl -X DELETE 'https://api.mbcom.cloud/api/comms/v1/inbound-hooks/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Change an inbound webhook (comms:admin)

`PATCH /api/comms/v1/inbound-hooks/{id}`

Module: Comms · operationId: `updateInboundHook` · Tag: Inbound webhooks · Auth: access token (`Authorization: Bearer <accessToken>`)

Changing the scheme creates a new secret, which the answer carries once; the old one stops working at once (it cannot verify the new scheme).

### Parameters

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

### Request body

`application/json` (required)

- `name` (string, required): Display name
- `config` (InboundConfig): Tunes the scheme to the sender; empty fields take the scheme's usual headers.
  - `idHeader` (string): Header with a unique delivery id; repeated ids are stored once
  - `prefix` (string): Text before the value, e.g. "sha256=" or "Bearer "
  - `signatureHeader` (string): Header with the signature (hmac_sha256) or the token (token)
- `enabled` (boolean): Disabled endpoints answer 404; omitted keeps the value (enabled on create)
- `maxBodyBytes` (integer): Largest accepted body (up to 1 MiB)
- `rev` (integer): Revision the change is based on (PATCH)
- `scheme` (string): How the sender is verified (one of `standard_webhooks`, `hmac_sha256`, `token`; default `"standard_webhooks"`)
- `toleranceSecs` (integer): Allowed clock difference for standard_webhooks (30–3600)

Example:

```json
{
  "config": {
    "idHeader": "X-Shop-Delivery",
    "prefix": "sha256=",
    "signatureHeader": "X-Shop-Signature"
  },
  "enabled": true,
  "maxBodyBytes": 262144,
  "name": "Shop-Bestellungen",
  "rev": 0,
  "scheme": "hmac_sha256"
}
```

### Responses

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

Fields of the 200 answer:

- `config` (InboundConfig): Tunes the scheme to the sender; empty fields take the scheme's usual headers.
  - `idHeader` (string): Header with a unique delivery id; repeated ids are stored once
  - `prefix` (string): Text before the value, e.g. "sha256=" or "Bearer "
  - `signatureHeader` (string): Header with the signature (hmac_sha256) or the token (token)
- `createdAt` (string (date-time)): Creation time
- `createdBy` (string): Who created the endpoint
- `enabled` (boolean): Disabled endpoints answer 404
- `id` (string (uuid)): Endpoint id
- `lastReceivedAt` (string (date-time)): Time of the last verified request
- `lastRejectedAt` (string (date-time)): Time of the last rejected request
- `lastRejectedReason` (string): Why the last request was rejected
- `maxBodyBytes` (integer): Largest accepted body in bytes
- `name` (string): Display name
- `receivedCount` (integer): Verified requests received
- `rejectedCount` (integer): Requests rejected by the check
- `rev` (integer): Revision for optimistic locking (send it back as `rev`)
- `scheme` (string): How the sender is verified
- `secret` (string): Only in the answer that created or rotated it
- `toleranceSecs` (integer): Allowed clock difference for standard_webhooks
- `url` (string): Public URL the sender posts to

Example 200 answer:

```json
{
  "config": {
    "idHeader": "X-Shop-Delivery",
    "prefix": "sha256=",
    "signatureHeader": "X-Shop-Signature"
  },
  "createdAt": "2026-10-01T10:20:00Z",
  "createdBy": "jonas.bauer@muster-it.example",
  "enabled": true,
  "id": "1a9e5c3b-7d2f-4e6a-b8c4-0d1e2f3a4b5c",
  "lastReceivedAt": "2026-11-18T07:55:32Z",
  "lastRejectedAt": "2026-11-02T13:10:04Z",
  "lastRejectedReason": "Signatur ungültig",
  "maxBodyBytes": 262144,
  "name": "Shop-Bestellungen",
  "receivedCount": 128,
  "rejectedCount": 2,
  "rev": 4,
  "scheme": "hmac_sha256",
  "toleranceSecs": 300,
  "url": "https://api.mbcom.cloud/api/comms/v1/hooks/f3Kq9ZpL2vXc8RtW1nYb4A"
}
```

### Example request

```bash
curl -X PATCH 'https://api.mbcom.cloud/api/comms/v1/inbound-hooks/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"config":{"idHeader":"X-Shop-Delivery","prefix":"sha256=","signatureHeader":"X-Shop-Signature"},"enabled":true,"maxBodyBytes":262144,"name":"Shop-Bestellungen","rev":0,"scheme":"hmac_sha256"}'
```

## Create a new secret (comms:admin)

`POST /api/comms/v1/inbound-hooks/{id}/rotate-secret`

Module: Comms · operationId: `rotateInboundHookSecret` · Tag: Inbound webhooks · Auth: access token (`Authorization: Bearer <accessToken>`)

The previous secret stays valid for 24 hours so the sender can switch over.

### Parameters

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

### Responses

- **200** Endpoint with the new secret (`application/json`)
- **404** Error (`application/json`)

Fields of the 200 answer:

- `config` (InboundConfig): Tunes the scheme to the sender; empty fields take the scheme's usual headers.
  - `idHeader` (string): Header with a unique delivery id; repeated ids are stored once
  - `prefix` (string): Text before the value, e.g. "sha256=" or "Bearer "
  - `signatureHeader` (string): Header with the signature (hmac_sha256) or the token (token)
- `createdAt` (string (date-time)): Creation time
- `createdBy` (string): Who created the endpoint
- `enabled` (boolean): Disabled endpoints answer 404
- `id` (string (uuid)): Endpoint id
- `lastReceivedAt` (string (date-time)): Time of the last verified request
- `lastRejectedAt` (string (date-time)): Time of the last rejected request
- `lastRejectedReason` (string): Why the last request was rejected
- `maxBodyBytes` (integer): Largest accepted body in bytes
- `name` (string): Display name
- `receivedCount` (integer): Verified requests received
- `rejectedCount` (integer): Requests rejected by the check
- `rev` (integer): Revision for optimistic locking (send it back as `rev`)
- `scheme` (string): How the sender is verified
- `secret` (string): Only in the answer that created or rotated it
- `toleranceSecs` (integer): Allowed clock difference for standard_webhooks
- `url` (string): Public URL the sender posts to

Example 200 answer:

```json
{
  "config": {
    "idHeader": "X-Shop-Delivery",
    "prefix": "sha256=",
    "signatureHeader": "X-Shop-Signature"
  },
  "createdAt": "2026-10-01T10:20:00Z",
  "createdBy": "jonas.bauer@muster-it.example",
  "enabled": true,
  "id": "1a9e5c3b-7d2f-4e6a-b8c4-0d1e2f3a4b5c",
  "lastReceivedAt": "2026-11-18T07:55:32Z",
  "lastRejectedAt": "2026-11-02T13:10:04Z",
  "lastRejectedReason": "Signatur ungültig",
  "maxBodyBytes": 262144,
  "name": "Shop-Bestellungen",
  "receivedCount": 128,
  "rejectedCount": 2,
  "rev": 4,
  "scheme": "hmac_sha256",
  "toleranceSecs": 300,
  "url": "https://api.mbcom.cloud/api/comms/v1/hooks/f3Kq9ZpL2vXc8RtW1nYb4A"
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/comms/v1/inbound-hooks/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/rotate-secret' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Stored requests of an inbound webhook, newest first (comms:read)

`GET /api/comms/v1/inbound-hooks/{id}/events`

Module: Comms · operationId: `listInboundHookEvents` · Tag: Inbound webhooks · Auth: access token (`Authorization: Bearer <accessToken>`)

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `limit` | query | integer |  | 1–200; anything else is 400 invalid (default `50`; max 200) |
| `offset` | query | integer |  | 0–10000; anything else is 400 invalid (default `0`; max 10000) |
| `id` | path | string (uuid) | yes |  |

### Responses

- **200** Requests (`application/json`)
- **404** Error (`application/json`)

Fields of the 200 answer:

- `items` (array of InboundEvent): Stored requests of the page (without body)
  - `bodySha256` (string): SHA-256 of the body, hex
  - `bodyText` (string): Body as text (pretty JSON when it is JSON); only in the detail
  - `bodyTruncated` (boolean): bodyText was cut off
  - `contentType` (string): Content-Type of the request
  - `endpointId` (string (uuid)): The inbound webhook that received it
  - `externalId` (string): The sender's delivery id, if it sends one
  - `headers` (object): Selected headers; never credentials
  - `id` (string (uuid)): Id of the stored request
  - `receivedAt` (string (date-time)): Time of receipt
  - `size` (integer): Body size in bytes
  - `sourceIp` (string): IP address of the sender
- `total` (integer): Number of stored requests

Example 200 answer:

```json
{
  "items": [
    {
      "bodySha256": "9f2c4a1e7b3d5f60a8c2e4b6d8f0a1c3e5b7d9f1a3c5e7b9d1f3a5c7e9b1d3f5",
      "contentType": "application/json",
      "endpointId": "1a9e5c3b-7d2f-4e6a-b8c4-0d1e2f3a4b5c",
      "externalId": "dlv_20261118_0042",
      "headers": {
        "User-Agent": "Shop-Webhooks/2.1",
        "X-Shop-Delivery": "dlv_20261118_0042"
      },
      "id": "8e2b4d6f-0a1c-4e3b-9d5f-7a8b9c0d1e2f",
      "receivedAt": "2026-11-18T07:55:32Z",
      "size": 129,
      "sourceIp": "203.0.113.24"
    }
  ],
  "total": 128
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/comms/v1/inbound-hooks/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/events' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## A stored request with its body (comms:read)

`GET /api/comms/v1/inbound-events/{id}`

Module: Comms · operationId: `getInboundEvent` · Tag: Inbound webhooks · Auth: access token (`Authorization: Bearer <accessToken>`)

### Parameters

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

### Responses

- **200** Request (`application/json`)
- **404** Error (`application/json`)

Fields of the 200 answer:

- `bodySha256` (string): SHA-256 of the body, hex
- `bodyText` (string): Body as text (pretty JSON when it is JSON); only in the detail
- `bodyTruncated` (boolean): bodyText was cut off
- `contentType` (string): Content-Type of the request
- `endpointId` (string (uuid)): The inbound webhook that received it
- `externalId` (string): The sender's delivery id, if it sends one
- `headers` (object): Selected headers; never credentials
- `id` (string (uuid)): Id of the stored request
- `receivedAt` (string (date-time)): Time of receipt
- `size` (integer): Body size in bytes
- `sourceIp` (string): IP address of the sender

Example 200 answer:

```json
{
  "bodySha256": "9f2c4a1e7b3d5f60a8c2e4b6d8f0a1c3e5b7d9f1a3c5e7b9d1f3a5c7e9b1d3f5",
  "bodyText": "{\n  \"event\": \"order.created\",\n  \"orderNo\": \"SO-10482\",\n  \"customer\": \"Alpenhotel Seeblick GmbH\",\n  \"total\": 1249.90,\n  \"currency\": \"EUR\"\n}",
  "bodyTruncated": false,
  "contentType": "application/json",
  "endpointId": "1a9e5c3b-7d2f-4e6a-b8c4-0d1e2f3a4b5c",
  "externalId": "dlv_20261118_0042",
  "headers": {
    "User-Agent": "Shop-Webhooks/2.1",
    "X-Shop-Delivery": "dlv_20261118_0042"
  },
  "id": "8e2b4d6f-0a1c-4e3b-9d5f-7a8b9c0d1e2f",
  "receivedAt": "2026-11-18T07:55:32Z",
  "size": 129,
  "sourceIp": "203.0.113.24"
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/comms/v1/inbound-events/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

# Mailbox import

## Import a mail again (comms:admin)

`POST /api/comms/v1/mailbox-mails/{messageId}/reimport`

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

Mailbox mails are moved back to the inbox folder and imported by the next run; platform mails are imported again from storage. All documents go to DMS again.

### Parameters

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

### Responses

- **202** Queued
- **404** Error (`application/json`)

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/comms/v1/mailbox-mails/string/reimport' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## The tenant's platform address of the Belegeingang (comms:read)

`GET /api/comms/v1/mail-intake`

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

Mail to the address is received by Amazon SES; PDF/XML attachments (category invoice) and the
raw mail (category mail) go to DMS like mailbox imports. `available` is false when the platform
has no mail domain; `address` is empty until an admin activated the intake. Addresses live on the tenant's
subdomain (`<local part>@<subdomain>.<mail domain>`, `mailDomain`); it is empty until an HR admin set the
subdomain in the HR settings, and activating then fails with 400 (field `subdomain`).

### Responses

- **200** Intake (`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 GET 'https://api.mbcom.cloud/api/comms/v1/mail-intake' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Activate (rev 0, creates the address) or switch the platform intake on or off (comms:admin)

`PUT /api/comms/v1/mail-intake`

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

### Request body

`application/json` (required)

- `enabled` (boolean): Switch the intake on or off
- `localPart` (string): Part before the @ on activation (default belege) (max length 40)
- `randomSuffix` (boolean): Adds a random suffix on activation (default true: a guessable Belege address invites forged invoices)
- `rev` (integer): 0 activates the intake

Example:

```json
{
  "enabled": true,
  "localPart": "belege",
  "randomSuffix": true,
  "rev": 0
}
```

### Responses

- **200** Intake (`application/json`)
- **400** Error (`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 PUT 'https://api.mbcom.cloud/api/comms/v1/mail-intake' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"enabled":true,"localPart":"belege","randomSuffix":true,"rev":0}'
```

## 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}'
```

## Mails received at the platform address, newest first (comms:read)

`GET /api/comms/v1/mail-intake/mails`

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

Reimport them with POST /mailbox-mails/{messageId}/reimport.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `state` | query | string |  | Comma-separated states, e.g. PENDING,REJECTED_FINAL |
| `limit` | query | integer |  | 1–200; anything else is 400 invalid (default `50`; max 200) |
| `offset` | query | integer |  | 0–10000; anything else is 400 invalid (default `0`; max 10000) |

### Responses

- **200** Mails (`application/json`)

Fields of the 200 answer:

- `items` (array of InboundMail): Mails of the page
  - `attachments` (array of string): File names of the attachments
  - `channelId` (string): Microsoft 365 connection (msgraph only)
  - `consumer` (string): The module the mail goes to (one of `invoice`, `desk`, `recruiting`)
  - `createdAt` (string (date-time)): When the mail was imported
  - `lastError` (string): Why the mail was rejected or failed
  - `mailbox` (string): The mailbox or platform address the mail came in on
  - `mailboxId` (string (uuid)): The mailbox that received the mail
  - `messageId` (string): Graph message id or SES message id
  - `receivedAt` (string (date-time)): When the mail was received
  - `selectedClassification` (string): Document type from "[CC:380]" in the subject
  - `sender` (string): Sender address
  - `source` (string): msgraph: a Microsoft 365 mailbox; ses: the platform address (one of `msgraph`, `ses`)
  - `state` (string): Import state; PENDING waits for the consumer (one of `PENDING`, `RETRY_MANUAL`, `ARCHIVED`, `REJECTED`, `DEAD_LETTER`, `COMPLETED`, `REJECTED_FINAL`)
  - `subject` (string): Subject
  - `updatedAt` (string (date-time)): Time of the last state change
- `total` (integer): Number of matching mails

Example 200 answer:

```json
{
  "items": [
    {
      "attachments": [
        "RE-2026-1187.pdf"
      ],
      "consumer": "invoice",
      "createdAt": "2026-11-18T06:47:13Z",
      "mailbox": "belege-k7m2qa@demo.on.beta.mbcom.dev",
      "mailboxId": "6a8c0e2f-4b5d-4c7e-9a1b-3c5d7e9f1a2b",
      "messageId": "0100018f2c7a1b3e-5d9f4c2a-7b1e-4a6d-9c3f-2e8a1b7d4c6f-000000",
      "receivedAt": "2026-11-18T06:47:12Z",
      "sender": "rechnung@buero-mueller.example",
      "source": "ses",
      "state": "PENDING",
      "subject": "Rechnung RE-2026-1187",
      "updatedAt": "2026-11-18T06:47:13Z"
    }
  ],
  "total": 1
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/comms/v1/mail-intake/mails' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

# Mailboxes

## Receiving mailboxes of the tenant (comms:read or desk:admin)

`GET /api/comms/v1/mailboxes`

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

Platform addresses (kind ses, received by Amazon SES) and Microsoft 365 mailboxes (kind msgraph, an address
read with a Microsoft 365 connection) for the Belegeingang (consumer invoice), the ticket system (consumer desk)
and recruiting (consumer recruiting). The platform address of the Belegeingang is changed through /mail-intake;
every other mailbox here. `mailDomain` is the tenant's
mail domain (`<subdomain>.<mail domain>`) platform addresses get; it is empty when the platform offers no
platform addresses or the tenant has no subdomain yet (an HR admin sets it in the HR settings).

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `consumer` | query | string |  | (one of `invoice`, `desk`, `recruiting`) |

### Responses

- **200** Mailboxes (`application/json`)

Fields of the 200 answer:

- `items` (array of Mailbox): The tenant's mailboxes the caller may see
  - `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
- `mailDomain` (string): The tenant's mail domain for platform addresses; empty without one
- `sesAvailable` (boolean): Whether the platform offers platform addresses (kind ses) at all

Example 200 answer:

```json
{
  "items": [
    {
      "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"
    },
    {
      "address": "bewerbung-r4t8wz@demo.on.beta.mbcom.dev",
      "consumer": "recruiting",
      "enabled": true,
      "id": "7f1b3d5e-9a2c-4e6f-8b0d-2a4c6e8f0b1d",
      "kind": "ses",
      "lastImported": 17,
      "lastReceivedAt": "2026-11-15T19:22:08Z",
      "name": "Bewerbungen",
      "pending": 0,
      "previous": [],
      "rev": 1,
      "updatedAt": "2026-08-12T09:00:00Z",
      "updatedBy": "christina.adler@muster-it.example"
    }
  ],
  "mailDomain": "demo.on.beta.mbcom.dev",
  "sesAvailable": true
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/comms/v1/mailboxes' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Create a mailbox (comms:admin, desk:admin or hr:recruiting:manage; Microsoft 365 only comms:admin)

`POST /api/comms/v1/mailboxes`

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

kind ses creates the address `<localPart>@<subdomain>.<mail domain>` (with `randomSuffix`
`<localPart>-<6 random characters>@…`) for consumer desk or recruiting; 400 with field `subdomain` while the
tenant has no subdomain, field `localPart` when the address is taken. kind msgraph reads the folders of the
mailbox `address` with the Microsoft 365 connection `channelId` (consumer desk, recruiting or invoice – the
Belegeingang moves new mail to the progress folder and queues its PDF/XML attachments and the raw mail for DMS;
the app needs Mail.ReadWrite, for answers Mail.Send). Several mailboxes may share a connection; 400 with field
`fetchFolder` when another mailbox of the connection reads the same folder of the same address.

### 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

- **201** Mailbox (`application/json`)
- **400** Error (`application/json`)
- **403** Error (`application/json`)

Fields of the 201 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 201 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 POST 'https://api.mbcom.cloud/api/comms/v1/mailboxes' \
  -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}'
```

## One mailbox (comms:read; desk:admin its ticket mailboxes, hr:recruiting:manage its applicant mailboxes – another module's mailbox answers 404)

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

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

### Parameters

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

### Responses

- **200** Mailbox (`application/json`)
- **404** 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 GET 'https://api.mbcom.cloud/api/comms/v1/mailboxes/string' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## 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}'
```

## Delete a mailbox with its addresses (comms:admin; desk:admin its ticket mailboxes, hr:recruiting:manage its applicant mailboxes; Microsoft 365 mailboxes only comms:admin)

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

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

### Parameters

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

### Responses

- **204** Deleted
- **403** Error (`application/json`)
- **404** Error (`application/json`)

### Example request

```bash
curl -X DELETE 'https://api.mbcom.cloud/api/comms/v1/mailboxes/string' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Replace the address of a ticket or applicant mailbox (kind ses); the old one is accepted for graceDays (default 14) (comms:admin; desk:admin its ticket mailboxes, hr:recruiting:manage its applicant mailboxes)

`POST /api/comms/v1/mailboxes/{id}/rotate`

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

### Parameters

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

### 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** 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 POST 'https://api.mbcom.cloud/api/comms/v1/mailboxes/string/rotate' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"graceDays":14,"randomSuffix":true,"rev":5}'
```

## Sign in with the mailbox's Microsoft 365 connection and look up the folders of its address (comms:read; desk:admin its ticket mailboxes, hr:recruiting:manage its applicant mailboxes – another module's mailbox answers 404)

`POST /api/comms/v1/mailboxes/{id}/check`

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

### Parameters

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

### Responses

- **200** Checks (`application/json`)
- **400** Error (`application/json`)
- **404** Error (`application/json`)

Fields of the 200 answer:

- `checks` (array of MailCheck): The single checks (sign-in, folders)
  - `detail` (string): Detail of the result
  - `label` (string): What was checked
  - `status` (string): Result of the check (one of `success`, `error`)
- `ok` (boolean): Every check succeeded

Example 200 answer:

```json
{
  "checks": [
    {
      "detail": "Die Verbindung „Microsoft 365 Muster IT“ hat sich angemeldet.",
      "label": "Anmeldung bei Microsoft 365",
      "status": "success"
    },
    {
      "detail": "Gefunden: Posteingang, In Bearbeitung, Erledigt, Abgelehnt.",
      "label": "Postfach support@muster-it.example",
      "status": "success"
    }
  ],
  "ok": true
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/comms/v1/mailboxes/string/check' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Mails received by a mailbox, newest first (comms:read; desk:admin its ticket mailboxes, hr:recruiting:manage its applicant mailboxes – another module's mailbox answers 404)

`GET /api/comms/v1/mailboxes/{id}/mails`

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

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `state` | query | string |  | Comma-separated states, e.g. PENDING,REJECTED_FINAL |
| `limit` | query | integer |  | 1–200; anything else is 400 invalid (default `50`; max 200) |
| `offset` | query | integer |  | 0–10000; anything else is 400 invalid (default `0`; max 10000) |
| `id` | path | string | yes |  |

### Responses

- **200** Mails (`application/json`)
- **400** Error (`application/json`)
- **404** Error (`application/json`)

Fields of the 200 answer:

- `items` (array of InboundMail): Mails of the page
  - `attachments` (array of string): File names of the attachments
  - `channelId` (string): Microsoft 365 connection (msgraph only)
  - `consumer` (string): The module the mail goes to (one of `invoice`, `desk`, `recruiting`)
  - `createdAt` (string (date-time)): When the mail was imported
  - `lastError` (string): Why the mail was rejected or failed
  - `mailbox` (string): The mailbox or platform address the mail came in on
  - `mailboxId` (string (uuid)): The mailbox that received the mail
  - `messageId` (string): Graph message id or SES message id
  - `receivedAt` (string (date-time)): When the mail was received
  - `selectedClassification` (string): Document type from "[CC:380]" in the subject
  - `sender` (string): Sender address
  - `source` (string): msgraph: a Microsoft 365 mailbox; ses: the platform address (one of `msgraph`, `ses`)
  - `state` (string): Import state; PENDING waits for the consumer (one of `PENDING`, `RETRY_MANUAL`, `ARCHIVED`, `REJECTED`, `DEAD_LETTER`, `COMPLETED`, `REJECTED_FINAL`)
  - `subject` (string): Subject
  - `updatedAt` (string (date-time)): Time of the last state change
- `total` (integer): Number of matching mails

Example 200 answer:

```json
{
  "items": [
    {
      "attachments": [
        "ap-restaurant.jpg"
      ],
      "channelId": "5e7a9c1b-3d4f-4a6b-9c8d-0e1f2a3b4c5d",
      "consumer": "desk",
      "createdAt": "2026-11-18T08:00:02Z",
      "mailbox": "support@muster-it.example",
      "mailboxId": "3d5f7a9b-1c2e-4f4a-8b6c-8d0e1f2a3b4c",
      "messageId": "AAMkAGI2THVSAAA=",
      "receivedAt": "2026-11-18T07:58:41Z",
      "sender": "it@alpenhotel-seeblick.example",
      "source": "msgraph",
      "state": "COMPLETED",
      "subject": "WLAN im Restaurant fällt aus",
      "updatedAt": "2026-11-18T08:00:05Z"
    }
  ],
  "total": 1
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/comms/v1/mailboxes/string/mails' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

