# Leer tu historial de envíos (/es/guides/email-logs)

Los webhooks te avisan cuando algo le ocurre a un mensaje. Esto te deja preguntar después, que es la
mitad que necesitas a las tres de la mañana cuando un cliente dice que no le llegó nada — para
entonces el webhook ya pasó.

## Listar

```bash
curl "https://api.bitelio.com/v1/emails?status=bounced&limit=50" \
  -H "Authorization: Bearer $BITELIO_API_KEY"
```

```json
{
  "data": [
    {
      "id": "…",
      "to": "cliente@ejemplo.com",
      "subject": "Tu recibo",
      "status": "BOUNCED",
      "error": "550 5.1.1 user unknown",
      "createdAt": "2026-09-01T09:14:22.108Z",
      "bouncedAt": "2026-09-01T09:14:25.902Z"
    }
  ],
  "nextCursor": "…"
}
```

Pagina con `cursor`, devolviendo tal cual el `nextCursor` que te dieron — es opaco, y es `null` en
la última página. No hay parámetro de offset: nada poda esta tabla, así que un offset profundo en
el historial de un proyecto grande es una consulta que empeora cada mes.

Filtros: `status`, `mode`, `to`, `since`, `until`, `limit` (hasta 100).

## Leer uno, con el cuerpo

```bash
curl "https://api.bitelio.com/v1/emails/$EMAIL_ID" \
  -H "Authorization: Bearer $BITELIO_API_KEY"
```

Este es el que responde a la pregunta de verdad. El listado te dice *si* algo se envió; esto
devuelve el HTML exacto que salió, ya con las variables sustituidas, los bloques resueltos y tu
identidad de marca aplicada. La mayoría de los «el email se ve mal» se resuelven leyéndolo.

El cuerpo no viene en el listado — son cientos de kilobytes por página.

## Los envíos de prueba están ocultos por defecto

`mode` es `live` salvo que digas otra cosa. Pasa `mode=test` para ver solo los de
[claves de prueba](/guides/api-keys), o `mode=all` para los dos. Un envío de prueba es interesante
durante diez minutos y ruido para siempre después, y por eso no es el valor por defecto.

## Lo que no se puede hacer

**No hay búsqueda por asunto ni por contenido.** Sobre una tabla de millones de filas eso es un
escaneo o un índice de texto completo que nadie mantiene, y preferimos decirlo a ofrecerlo y ser
lentos. Filtra por destinatario, estado y fecha.

**`to` solo encuentra tus propios contactos.** La dirección se resuelve primero a un contacto de tu
proyecto, así que una dirección a la que nunca has escrito devuelve una página vacía, no un error.

## Permiso

Los endpoints necesitan el permiso **`emails:view`**. Es distinto de `analytics:view` porque ese son
agregados, y leer un cuerpo es leer datos personales de un destinatario — solo Owner y Admin lo
tienen por defecto.

<Cards>
  <Card title="Webhooks" href="/webhooks">
    La mitad push: que te avisen cuando un mensaje se entrega, se abre o rebota
  </Card>

  <Card title="Claves de API" href="/guides/api-keys">
    Cómo limitar una clave, y qué hace una de prueba
  </Card>
</Cards>