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