# Listar emails (/es/api-reference/public-api/listEmails)

`GET /v1/emails`

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

El historial de envíos del proyecto, del más reciente al más antiguo, paginado **por cursor**. Por defecto solo muestra envíos reales; usa `mode` para ver los de prueba.

No hay búsqueda por asunto ni por contenido, a propósito: sobre millones de filas sería un escaneo, y decirlo es mejor que ofrecerlo y ser lento.

El cuerpo renderizado **no** viene en el listado — son cientos de kilobytes por página. Está en `GET /v1/emails/{id}`.

## Query parameters

- `limit`: integer — Page size.
- `cursor`: string — El `nextCursor` de la página anterior. Opaco: devuélvelo tal cual.
- `mode`: enum ("live" | "test" | "all") — Qué envíos mostrar.
- `status`: enum ("PENDING" | "SENDING" | "HELD" | "SENT" | "DELIVERED" | "RECEIVED" | "OPENED" | "CLICKED" | "BOUNCED" | "COMPLAINED" | "FAILED") — Filtrar por estado de entrega.
- `to`: string (email) — Dirección del destinatario. Sin resultados si no es contacto del proyecto.
- `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'
```