Filtrado y ordenación

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:

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

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, Listar plantillas, Listar automatizaciones y Listar direcciones bloqueadas, 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.

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:

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, 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:

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:

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 -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"

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();

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 (GET /emails).

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 (GET /domains).

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

Claves de API

Listar claves de API (GET /api-keys).

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

Listas de contactos y suscriptores

Listar listas de contactos (GET /audiences) acepta name (cadena) y created_at (fecha), además de search.

Listar suscriptores (GET /audiences/{id}/subscribers):

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

Contactos

Listar contactos (GET /contacts) y Exportar contactos.

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 (GET /campaigns).

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

Formularios

Listar formularios (GET /forms).

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

Automatizaciones

Listar automatizaciones (GET /automations).

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 (GET /automations/{id}/runs) acepta status (cadena), event (cadena) y created_at (fecha).

Plantillas

Listar plantillas (GET /templates). Solo se listan las versiones publicadas.

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 (GET /suppressions).

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:

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

Eventos

Listar eventos (GET /events).

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

Webhooks

Listar webhooks (GET /webhooks).

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

Listas de direcciones (verificación masiva)

Listar listas (GET /email-verification-lists) acepta name (cadena), status (cadena) y created_at (fecha), además de search y status.

Listar resultados (GET /email-verification-lists/{id}/results):

También acepta status y result.

Informes DMARC

Listar informes agregados y Listar informes forenses.

También acepta type, status, org_name, from y to. Las listas DMARC se paginan con limit y offset. Consulta Paginación.

Ver también