# List emails (/api-reference/public-api/listEmails)

`GET /v1/emails`

Base URL: `https://api.bitelio.com`

The project's send history, newest first, **cursor-paginated**. Shows live sends only by default; use `mode` to see test sends.

There is deliberately no search by subject or body: over millions of rows that is a scan, and saying so is better than offering it and being slow.

The rendered body is **not** in the listing — that is hundreds of kilobytes a page. It is on `GET /v1/emails/{id}`.

## Query parameters

- `limit`: integer — Page size.
- `cursor`: string — The previous page's `nextCursor`. Opaque — return it verbatim.
- `mode`: enum ("live" | "test" | "all") — Which sends to show.
- `status`: enum ("PENDING" | "SENDING" | "HELD" | "SENT" | "DELIVERED" | "RECEIVED" | "OPENED" | "CLICKED" | "BOUNCED" | "COMPLAINED" | "FAILED") — Filter by delivery status.
- `to`: string (email) — Recipient address. Empty if they are not a contact of this project.
- `since`: string (date-time) — ISO 8601.
- `until`: string (date-time) — ISO 8601.

## Responses

### `200` — OK

- `data`: array<object>
  items:
- `nextCursor`: string — null on the last page.

```json
{
  "data": [
    null
  ],
  "nextCursor": "string"
}
```

### `400` — Invalid limit, mode, status or date

### `403` — The key lacks the emails:view scope

## Example request

```bash
curl -X GET 'https://api.bitelio.com/v1/emails' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```