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