# List email delivery logs

Retrieve a paginated list of outbound notification email delivery logs for the organization.

Source: https://statusdashboard.com/docs/api/notifications/email/list

`GET /app/notifications/email/logs`

Returns a newest-first paginated list of email delivery log entries for notification-channel sends (event notifications and subscription emails). Each entry records the provider handoff and any subsequent lifecycle events.

Requires the `admin` or `subscriber` role and the **Email notifications** feature entitlement.

***

## Request
See [API Basics](/docs/api) for required headers.

### Query parameters
| Parameter   | Type    | Required | Description                                                                                              |
| ----------- | ------- | -------- | -------------------------------------------------------------------------------------------------------- |
| `limit`     | integer | No       | Max entries per page. Range: 1–100. Default: `10`.                                                       |
| `nextToken` | string  | No       | Next-page bookmark from the previous response — pass unchanged. See [Pagination](/docs/api#pagination).  |
| `recipient` | string  | No       | Filter logs to an exact recipient email address (case-insensitive). Must be a valid email when provided. |

***

## Sample request
```bash
curl "https://api.statusdashboard.com/app/notifications/email/logs?recipient=subscriber@example.com" \
  -H "Authorization: Bearer bcf847abf5c6:def456"
```

## Sample response
**Status: `200 OK`**

```json
{
  "logs": [
    {
      "logId": "019670ab-cdef-7234-b5f1-abc123def456",
      "sentAt": "2026-06-26T14:30:00.000Z",
      "recipient": "subscriber@example.com",
      "sender": "StatusDashboard <support@statusdashboard.com>",
      "subject": "[Acme Corp][incident: Investigating] API latency spike",
      "status": "delivered",
      "emailType": "event_notification",
      "sesMessageId": "0100018abc1234-5678-90ab-cdef-EXAMPLE",
      "dashboardId": "550e8400-e29b-41d4-a716-446655440000",
      "dashboardName": "Acme Status",
      "eventId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
      "changeType": "created",
      "events": [
        { "type": "Accepted", "at": "2026-06-26T14:30:00.000Z" },
        { "type": "Send", "at": "2026-06-26T14:30:00.100Z" },
        { "type": "Delivery", "at": "2026-06-26T14:30:02.000Z" }
      ]
    }
  ],
  "nextToken": null
}
```

***

## Response fields
| Field       | Type           | Description                                                                         |
| ----------- | -------------- | ----------------------------------------------------------------------------------- |
| `logs`      | array          | Delivery log entries for this page, newest first.                                   |
| `nextToken` | string \| null | Next-page bookmark when more results exist. See [Pagination](/docs/api#pagination). |

### Log entry fields
Each `logs[]` item:

| Field           | Type              | Description                                                                                                          |
| --------------- | ----------------- | -------------------------------------------------------------------------------------------------------------------- |
| `logId`         | string            | Opaque unique identifier for the log entry.                                                                          |
| `sentAt`        | string            | ISO 8601 timestamp when the send was initiated.                                                                      |
| `recipient`     | string            | Recipient email address.                                                                                             |
| `sender`        | string            | From address used for the send.                                                                                      |
| `subject`       | string            | Email subject line.                                                                                                  |
| `status`        | string            | Aggregate status: `submitted`, `sent`, `delivered`, `bounced`, `complained`, `rejected`, `failed`, or `suppressed`.  |
| `emailType`     | string            | `event_notification`, `subscription_verify`, `subscription_manage`, or `integration_failure`.                        |
| `sesMessageId`  | string \| omitted | message ID after successful handoff.                                                                                 |
| `dashboardId`   | string \| omitted | Dashboard UUID when applicable.                                                                                      |
| `dashboardName` | string \| omitted | Dashboard display name when applicable.                                                                              |
| `eventId`       | string \| omitted | Event UUID for event notification emails.                                                                            |
| `changeType`    | string \| omitted | Event notification change type (`created`, `updated`, `timeline`, `reopened`, `maintenance-advance`, `post-mortem`). |
| `events`        | array             | Chronological lifecycle events (see below).                                                                          |
| `failureReason` | string \| omitted | Error summary when `status` is `failed`.                                                                             |

### Event object fields
| Field          | Type               | Description                                                             |
| -------------- | ------------------ | ----------------------------------------------------------------------- |
| `type`         | string             | Event type (`Accepted`, `Send`, `Delivery`, `Bounce`, etc.).            |
| `at`           | string             | ISO 8601 timestamp.                                                     |
| `detail`       | string \| omitted  | Short summary (e.g. bounce type/subtype).                               |
| `raw`          | string \| omitted  | bounce object JSON (diagnostics only). Present on `Bounce` events only. |
| `rawBytes`     | number \| omitted  | Original byte length of `raw` before any truncation.                    |
| `rawTruncated` | boolean \| omitted | `true` when `raw` was truncated at 16 KB.                               |

### `suppressed` status
When `status` is `suppressed`, the recipient was on the organization's suppression list and the message was **not** handed to the StatusDashboard transactional email provider. These rows are written at send time and do not receive lifecycle events. No email message quota is consumed.

***

## Pagination
See [Pagination](/docs/api#pagination) in API Basics. Re-send the same query parameters on every page request.

***

## Retention
Log entries are retained for **30 days** and then automatically deleted.

***

## Error responses
| Status | When                                                                          |
| ------ | ----------------------------------------------------------------------------- |
| `400`  | Invalid query parameters (e.g. malformed `recipient`).                        |
| `403`  | Not an admin, or the Email notifications feature is not enabled on your plan. |