# Filtrado y ordenación

> Filtra y ordena los endpoints de listado de la API con parámetros de consulta key.condition=value, match y order. Todas las condiciones y los campos filtrables de cada recurso.

Los endpoints de listado aceptan el mismo lenguaje de filtros plano en la cadena de consulta: un parámetro de consulta por filtro, combinados con `match` y ordenados con `order` y `direction`. Esta página explica la sintaxis, las condiciones de cada tipo de campo y todos los campos por los que puedes filtrar y ordenar, recurso por recurso.

## Sintaxis

Un filtro es un parámetro de consulta llamado `<key>.<condition>` con el valor con el que se compara:

```text
GET /v2/emails?status.exact=bounced&created_at.after=2026-09-01
```

| Parámetro | Descripción |
| --- | --- |
| `<key>.<condition>=<value>` | Un filtro. Añade tantos como necesites, incluso varios sobre la misma clave. |
| `match` | Cómo se combinan los filtros. `all` (por defecto) devuelve las filas que cumplen todos los filtros. `or` devuelve las filas que cumplen al menos uno. |
| `order` | La clave por la que se ordena. Debe ser una de las claves de ordenación del endpoint. |
| `direction` | `asc` o `desc`. Si pasas `order` sin `direction`, los resultados se ordenan de forma ascendente. |

Sin `order`, las listas devuelven primero los objetos más recientes.

Los filtros se combinan con AND con los parámetros específicos del endpoint, como `search` o `type`. `match` solo controla cómo se combinan entre sí los filtros `key.condition`.

Las claves desconocidas, las condiciones que no encajan con el tipo de la clave y los valores que no se pueden interpretar (una fecha no válida, algo que no es un número, un valor de enumeración que no existe o un valor vacío) se ignoran en lugar de rechazarse. Si un filtro parece no tener efecto, comprueba cómo lo has escrito.

### Parámetros de ordenación heredados

Algunos endpoints también aceptan `sort=<key>` con `order=asc` u `order=desc`. En [Listar contactos](/es/docs/api-reference/contacts/list/), [Listar plantillas](/es/docs/api-reference/templates/list/), [Listar automatizaciones](/es/docs/api-reference/automations/list/) y [Listar direcciones bloqueadas](/es/docs/api-reference/suppressions/list/), `order` solo acepta `asc` o `desc`, así que ordena esas listas con `sort=<key>&order=<direction>` en lugar de `order=<key>`. La forma heredada funciona en todos los endpoints de listado.

## Condiciones

Cada clave tiene un tipo, y cada tipo acepta sus propias condiciones.

| Condición | Cadena | Número | Fecha | Booleano | Enumeración | Coincide cuando el campo… |
| --- | --- | --- | --- | --- | --- | --- |
| `exact` | Sí | Sí | Sí | Sí | Sí | es igual al valor. Las cadenas distinguen entre mayúsculas y minúsculas. Las fechas se comparan por día natural. |
| `not_exact` | Sí | Sí |  | Sí | Sí | no es igual al valor. |
| `contains` | Sí |  |  |  |  | contiene el valor, sin distinguir mayúsculas y minúsculas. |
| `not_contains` | Sí |  |  |  |  | no contiene el valor, sin distinguir mayúsculas y minúsculas. Los campos vacíos coinciden. |
| `starts_with` | Sí |  |  |  |  | empieza por el valor, sin distinguir mayúsculas y minúsculas. |
| `ends_with` | Sí |  |  |  |  | termina en el valor, sin distinguir mayúsculas y minúsculas. |
| `gt`, `gte` | | Sí |  |  |  | es mayor que el valor (o igual). |
| `lt`, `lte` | | Sí |  |  |  | es menor que el valor (o igual). |
| `before` |  |  | Sí |  |  | es anterior al valor. |
| `after` |  |  | Sí |  |  | es posterior al valor. |
| `empty` | Sí | Sí | Sí |  |  | no tiene valor. En las cadenas, una cadena vacía cuenta como vacía. |
| `not_empty` | Sí | Sí | Sí |  |  | tiene un valor. |

Formatos de los valores:

- **Fechas.** Cualquier fecha o fecha y hora en formato ISO 8601, como `2026-09-01` o `2026-09-01T14:30:00Z`. `before` y `after` son exclusivas.
- **Booleanos.** `true` o `1` significan verdadero. Cualquier otro valor significa falso.
- **Enumeraciones.** Uno de los valores que se indican para la clave más abajo.
- **`empty` y `not_empty`.** El valor se ignora, pero el parámetro necesita uno. Usa `1`, por ejemplo `spam_score.empty=1`.

## Ejemplos

Emails rebotados o fallidos desde el 1 de septiembre:

```text
GET /v2/emails?status.exact=bounced&status.exact=failed&match=or&date_from=2026-09-01
```

Como `match=or` se aplica a todos los filtros de la petición, no puedes mezclar AND y OR. Para combinar un rango de fechas con estados alternativos en [Listar emails](/es/docs/api-reference/emails/list/), usa el parámetro específico `date_from` para la fecha, como en el ejemplo, ya que los parámetros específicos siempre se aplican con AND.

Contactos de Acme cuyo campo personalizado `plan` es `pro`, ordenados por email:

```text
GET /v2/contacts?email.ends_with=%40acme.com&custom_fields.plan.exact=pro&sort=email&order=asc
```

Dominios con un registro DKIM que falla, de más antiguo a más reciente:

```text
GET /v2/domains?dkim_status.not_exact=ok&order=created_at&direction=asc
```

### Codificación de URL

Codifica los caracteres reservados de los valores: `+` como `%2B`, `&` como `%26`, `#` como `%23`, un espacio como `%20` y `@` como `%40`. Un `+` sin codificar en una dirección como `ada+news@example.com` se interpreta como un espacio. Con cURL, `-G` y `--data-urlencode` se encargan de la codificación por ti:

**cURL**

```bash
curl -G https://api.emailit.com/v2/emails \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  --data-urlencode "to.exact=ada+news@example.com" \
  --data-urlencode "subject.contains=order #1042" \
  --data-urlencode "order=created_at" \
  --data-urlencode "direction=desc"
```

**Node.js**

```javascript
const params = new URLSearchParams({
  'to.exact': 'ada+news@example.com',
  'subject.contains': 'order #1042',
  order: 'created_at',
  direction: 'desc',
});

const response = await fetch(`https://api.emailit.com/v2/emails?${params}`, {
  headers: { Authorization: `Bearer ${process.env.EMAILIT_API_KEY}` },
});
const { data } = await response.json();
```

**Python**

```python
import os
import requests

response = requests.get(
    "https://api.emailit.com/v2/emails",
    headers={"Authorization": f"Bearer {os.environ['EMAILIT_API_KEY']}"},
    params={
        "to.exact": "ada+news@example.com",
        "subject.contains": "order #1042",
        "order": "created_at",
        "direction": "desc",
    },
)
data = response.json()["data"]
```

## Campos filtrables

Salvo que una nota indique lo contrario, todas las claves de estas tablas también son claves de ordenación.

### Emails

[Listar emails](/es/docs/api-reference/emails/list/) (`GET /emails`).

| Clave | Tipo | Notas |
| --- | --- | --- |
| `to` | cadena | Dirección del destinatario. |
| `from` | cadena | Remitente tal como se envió, incluido el nombre visible, si lo hay. |
| `subject` | cadena | |
| `status` | enumeración | `accepted`, `scheduled`, `delivered`, `loaded`, `clicked`, `attempted`, `bounced`, `failed`, `rejected`, `suppressed`, `received`, `complained`, `canceled`, `held` |
| `tag` | cadena | La etiqueta del email. Por ahora, los envíos por la API o por SMTP no asignan ninguna etiqueta. |
| `spam_score` | número | |
| `created_at` | fecha | No amplía la ventana por defecto de 14 días. Usa `date_from` para emails más antiguos. |
| `updated_at` | fecha | |
| `api_key_id` | cadena | El ID `key_…` de la clave de API que envió el email. |
| `sending_domain_id` | cadena | El ID `dom_…` del dominio de envío. |

También acepta `search`, `type` (`outbound` o `inbound`), `date_from` y `date_to`, además de los parámetros antiguos `status`, `rcpt_to`, `mail_from`, `subject`, `api_key_id` y `sending_domain_id`.

### Dominios

[Listar dominios](/es/docs/api-reference/domains/list/) (`GET /domains`).

| Clave | Tipo | Notas |
| --- | --- | --- |
| `name` | cadena | |
| `created_at` | fecha | |
| `spf_status` | enumeración | `ok`, `missing`, `invalid` |
| `dkim_status` | enumeración | `ok`, `missing`, `invalid` |
| `return_path_status` | enumeración | `ok`, `missing`, `invalid` |

También acepta `search` (el nombre del dominio contiene el valor).

### Claves de API

[Listar claves de API](/es/docs/api-reference/api-keys/list/) (`GET /api-keys`).

| Clave | Tipo | Notas |
| --- | --- | --- |
| `name` | cadena | |
| `scope` | cadena | `full` o `sending`. |
| `type` | cadena | Tipo de credencial. Las claves creadas en el panel o con la API son `api`. |
| `created_at` | fecha | |

También acepta `search` (el nombre contiene el valor).

### Listas de contactos y suscriptores

[Listar listas de contactos](/es/docs/api-reference/audiences/list/) (`GET /audiences`) acepta `name` (cadena) y `created_at` (fecha), además de `search`.

[Listar suscriptores](/es/docs/api-reference/audiences/subscribers/list/) (`GET /audiences/{id}/subscribers`):

| Clave | Tipo | Notas |
| --- | --- | --- |
| `email` | cadena | La dirección de email del contacto. |
| `first_name` | cadena | |
| `last_name` | cadena | |
| `subscribed` | booleano | |
| `created_at` | fecha | Cuándo se unió el contacto a la lista. |

También acepta `search` (el email, el nombre o el apellido contienen el valor) y `subscribed=true|false`.

### Contactos

[Listar contactos](/es/docs/api-reference/contacts/list/) (`GET /contacts`) y [Exportar contactos](/es/docs/api-reference/contacts/export/).

| Clave | Tipo | Notas |
| --- | --- | --- |
| `email` | cadena | |
| `first_name` | cadena | |
| `last_name` | cadena | |
| `name` | cadena | Nombre y apellido unidos por un espacio. |
| `audiences` | cadena | El nombre de la primera lista de contactos del contacto por orden alfabético. |
| `unsubscribed` | booleano | Solo para filtrar. |
| `created_at` | fecha | |
| `updated_at` | fecha | |
| `audience_id` | cadena | Solo para filtrar. Solo `exact` y `not_exact`. El valor es un ID de lista de contactos (`aud_…`). |
| `custom_fields.<key>` | cadena | Solo para filtrar. Sustituye `<key>` por la clave del campo personalizado, por ejemplo `custom_fields.company.contains=Acme`. Los valores se comparan como texto. |

Ordena los contactos con `sort` igual a `email`, `first_name`, `last_name`, `name`, `audiences`, `created_at` o `updated_at`, y `order` igual a `asc` o `desc`. También acepta `search` (alias `q`), `audience_id` y `unsubscribed`. Las formas antiguas `filter[audience_id]`, `filter[unsubscribed]` y `filter[custom_fields][<key>]` siguen funcionando.

### Campañas

[Listar campañas](/es/docs/api-reference/campaigns/list/) (`GET /campaigns`).

| Clave | Tipo | Notas |
| --- | --- | --- |
| `name` | cadena | |
| `subject` | cadena | |
| `status` | enumeración | `draft`, `scheduled`, `queued`, `sending`, `sent`, `archived` |
| `created_at` | fecha | |
| `sent_at` | fecha | |

También acepta `search` (el nombre o el asunto contienen el valor).

### Formularios

[Listar formularios](/es/docs/api-reference/forms/list/) (`GET /forms`).

| Clave | Tipo | Notas |
| --- | --- | --- |
| `name` | cadena | |
| `type` | enumeración | `popup`, `full_page`, `flyout`, `embed`, `banner` |
| `status` | enumeración | `draft`, `live` |
| `created_at` | fecha | |

También acepta `search` (el nombre contiene el valor).

### Automatizaciones

[Listar automatizaciones](/es/docs/api-reference/automations/list/) (`GET /automations`).

| Clave | Tipo | Notas |
| --- | --- | --- |
| `name` | cadena | |
| `status` | enumeración | Solo para filtrar. `draft`, `running`, `paused`, `stopped`, `archived` |
| `context` | cadena | Solo para filtrar. `contact`, `email` o `event`. |
| `created_at` | fecha | |

Ordena con `sort` igual a `name`, `created_at`, `updated_at` o `last_triggered_at`, y `order` igual a `asc` o `desc`. También acepta `filter[name]`, `filter[status]` y `filter[context]`.

[Listar ejecuciones](/es/docs/api-reference/automations/runs/) (`GET /automations/{id}/runs`) acepta `status` (cadena), `event` (cadena) y `created_at` (fecha).

### Plantillas

[Listar plantillas](/es/docs/api-reference/templates/list/) (`GET /templates`). Solo se listan las versiones publicadas.

| Clave | Tipo | Notas |
| --- | --- | --- |
| `name` | cadena | |
| `alias` | cadena | |
| `editor` | cadena | Solo para filtrar. `html`, `text`, `dragit` o `tiptap`. |
| `subject` | cadena | Solo para filtrar. |
| `created_at` | fecha | |

Ordena con `sort` igual a `name`, `alias`, `created_at`, `updated_at` o `published_at`, y `order` igual a `asc` o `desc`. También acepta `filter[name]`, `filter[alias]` y `filter[editor]`.

### Direcciones bloqueadas

[Listar direcciones bloqueadas](/es/docs/api-reference/suppressions/list/) (`GET /suppressions`).

| Clave | Tipo | Notas |
| --- | --- | --- |
| `email` | cadena | |
| `reason` | cadena | |
| `type` | cadena | |
| `created_at` | fecha | |
| `keep_until` | fecha | Solo para filtrar. |

Ordena con `sort` igual a `email`, `reason`, `type` o `created_at`, y `order` igual a `asc` o `desc`. También acepta `search` (alias `q`; el email o el motivo contienen el valor).

Las direcciones bloqueadas también aceptan un generador de filtros JSON en el parámetro `filters` (alias `filter`). Pasa un objeto JSON codificado para URL:

```json
{
  "match": "any",
  "rules": [
    { "field": "reason", "operator": "contains", "value": "bounce" },
    { "field": "type", "operator": "in", "value": "recipient,campaign" }
  ]
}
```

| Propiedad | Descripción |
| --- | --- |
| `match` | `all` (por defecto) o `any`. |
| `rules` | Hasta 25 reglas. Las reglas con un campo o un operador desconocidos se ignoran. |
| `rules[].field` | `email`, `reason`, `type` o `created_at`. |
| `rules[].operator` | `equals`, `not_equals`, `contains`, `not_contains`, `starts_with`, `ends_with`, `greater_than`, `less_than`, `in`, `not_in`, `is_set` o `is_not_set`. |
| `rules[].value` | El valor con el que se compara. Para `in` y `not_in`, una lista separada por comas. No hace falta con `is_set` ni `is_not_set`. |

### Eventos

[Listar eventos](/es/docs/api-reference/events/list/) (`GET /events`).

| Clave | Tipo | Notas |
| --- | --- | --- |
| `type` | cadena | El tipo de evento, como `email.delivered`. |
| `created_at` | fecha | Cualquier filtro `created_at` sustituye la ventana por defecto de dos días. |

También acepta `type` como lista separada por comas de tipos de evento exactos, e `include_data`.

### Webhooks

[Listar webhooks](/es/docs/api-reference/webhooks/list/) (`GET /webhooks`).

| Clave | Tipo | Notas |
| --- | --- | --- |
| `name` | cadena | |
| `url` | cadena | |
| `enabled` | booleano | |
| `created_at` | fecha | |

También acepta `search` (el nombre o la URL contienen el valor).

### Listas de direcciones (verificación masiva)

[Listar listas](/es/docs/api-reference/email-verifications/lists/list/) (`GET /email-verification-lists`) acepta `name` (cadena), `status` (cadena) y `created_at` (fecha), además de `search` y `status`.

[Listar resultados](/es/docs/api-reference/email-verifications/lists/results/) (`GET /email-verification-lists/{id}/results`):

| Clave | Tipo | Notas |
| --- | --- | --- |
| `email` | cadena | |
| `status` | cadena | |
| `result` | cadena | Por ejemplo, `safe`, `invalid` o `disposable`. |
| `risk` | cadena | `low`, `medium` o `high`. |
| `created_at` | fecha | |

También acepta `status` y `result`.

### Informes DMARC

[Listar informes agregados](/es/docs/api-reference/dmarc/list/) y [Listar informes forenses](/es/docs/api-reference/dmarc/forensic/).

| Clave | Tipo | Notas |
| --- | --- | --- |
| `type` | cadena | `aggregate` o `forensic`. |
| `status` | cadena | |
| `org_name` | cadena | La organización que envió el informe. |
| `created_at` | fecha | Cuándo recibió Emailit el informe. |

También acepta `type`, `status`, `org_name`, `from` y `to`. Las listas DMARC se paginan con `limit` y `offset`. Consulta [Paginación](/es/docs/api-reference/pagination/).

## Ver también

  - [Paginación](/es/docs/api-reference/pagination/): Recorre los resultados de las listas página a página.
  - [Todos los endpoints](/es/docs/api-reference/endpoints/): Todos los endpoints y el permiso que necesitan.

---
Fuente: https://emailit.com/es/docs/api-reference/filtering/