# List emails

> Browse delivery logs with cursor pagination and focused filters.

`GET https://api-connect.nxiom.com/api/v1/emails/logs`

## Authorization

Requires `email.full_access`.

## Query parameters

| Field | Type | Description |
| --- | --- | --- |
| `limit` | integer · optional | 1–100; defaults to 50. |
| `cursor` | string · optional | The previous response's `nextCursor`; maximum 1,024 characters. |
| `status` | string · optional | `scheduled`, `canceled`, `queued`, `sending`, `accepted`, `delivered`, `bounced`, `complained`, `failed`, or `suppressed`. |
| `source` | string · optional | Filter by sending source, such as `api` or `smtp`. |
| `recipient` | string · optional | Filter by recipient. |
| `search` | string · optional | Search delivery logs. |
| `contactId` | string · optional | Filter by contact. |
| `templateId` | string · optional | Filter by template. |
| `startDate` | date string · optional | Start of the date filter, as an ISO 8601 timestamp. |
| `endDate` | date string · optional | End of the date filter, as an ISO 8601 timestamp. |

## Request

### cURL

```shell
curl "https://api-connect.nxiom.com/api/v1/emails/logs?limit=50&status=delivered" \
  -H "Authorization: Bearer $NEXIOM_API_KEY"
```

### Node.js

```typescript
import { NexiomConnect } from '@nexiom/connect';

const apiKey = process.env.NEXIOM_API_KEY;
if (!apiKey) throw new Error('Set NEXIOM_API_KEY');

const nexiom = new NexiomConnect({ apiKey });

const { data, error } = await nexiom.emails.list({ limit: 50, status: 'delivered' });

if (error) throw new Error(`${error.code}: ${error.message}`);
for (const delivery of data.items) {
  console.log(delivery.id, delivery.recipient, delivery.status);
}

// nextCursor is null on the last page.
console.log(data.nextCursor ?? 'last page');
```

### PHP

```php
<?php

use Nexiom\Connect\NexiomConnect;

$apiKey = getenv('NEXIOM_API_KEY');
if (!$apiKey) {
    throw new RuntimeException('Set NEXIOM_API_KEY');
}

$nexiom = new NexiomConnect($apiKey);

$page = $nexiom->emails->list(['limit' => 50, 'status' => 'delivered']);

foreach ($page['items'] as $delivery) {
    echo $delivery['id'], ' ', $delivery['recipient'], ' ', $delivery['status'], PHP_EOL;
}

// nextCursor is null on the last page.
echo $page['nextCursor'] ?? 'last page';
```

## Response

HTTP `200`. The response contains a collection of delivery summaries.

Each item contains `id`, `created_at`, `recipient`, `subject`, `status`, and `scheduled_at` (the scheduled send time, or `null`). Use that item's `id` to [retrieve the delivery](/docs/api/emails/retrieve).

`total` can be `null`. Continue with `nextCursor` while `hasMore` is true; see [Pagination](/docs/api/pagination).

### 200 OK

Example successful response.

```json
{
  "message": "Email logs fetched",
  "data": {
    "items": [
      {
        "id": "delivery_example",
        "created_at": "2026-10-02T10:00:00.000Z",
        "recipient": "reader@example.com",
        "subject": "Welcome",
        "status": "delivered",
        "scheduled_at": null
      }
    ],
    "total": 1,
    "limit": 50,
    "hasMore": false,
    "nextCursor": null
  }
}
```

### 400 Bad Request

The request is invalid. Correct it before retrying; `details` lists the failing fields.

```json
{
  "error": "invalid_argument",
  "message": "Request doesn't match the schema",
  "correlationId": "req_example",
  "details": {
    "context": "body",
    "issues": []
  }
}
```

### 401 Unauthorized

The API key is missing, malformed, revoked, or expired.

```json
{
  "error": "unauthorized",
  "message": "Invalid API key",
  "correlationId": "req_example"
}
```

### 403 Forbidden

The API key lacks a required permission, or its domain restriction does not allow this sender.

```json
{
  "error": "not_allowed",
  "message": "Missing required API key permissions: email.full_access",
  "correlationId": "req_example"
}
```

---

Source: https://connect.nxiom.com/docs/api/emails/list