Filtrage et tri

Les endpoints de liste acceptent tous le même langage de filtres à plat dans la chaîne de requête : un paramètre de requête par filtre, combinés avec match et triés avec order et direction. Cette page présente la syntaxe, les conditions de chaque type de champ et tous les champs sur lesquels vous pouvez filtrer et trier, ressource par ressource.

Syntaxe

Un filtre est un paramètre de requête nommé <key>.<condition>, dont la valeur est celle à comparer :

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

Sans order, les listes renvoient les objets les plus récents en premier.

Les filtres sont combinés en ET avec les paramètres dédiés de l’endpoint, comme search ou type. match ne règle que la façon dont les filtres key.condition se combinent entre eux.

Les clés inconnues, les conditions qui ne correspondent pas au type de la clé et les valeurs impossibles à analyser (une date invalide, une valeur non numérique, une valeur d’énumération inexistante ou une valeur vide) sont ignorées plutôt que rejetées. Si un filtre semble sans effet, vérifiez son orthographe.

Anciens paramètres de tri

Certains endpoints acceptent aussi sort=<key> avec order=asc ou order=desc. Sur Lister les contacts, Lister les modèles, Lister les automatisations et Lister les adresses bloquées, order n’accepte que asc ou desc : triez donc ces listes avec sort=<key>&order=<direction> plutôt qu’avec order=<key>. L’ancienne forme fonctionne sur tous les endpoints de liste.

Conditions

Chaque clé a un type, et chaque type accepte ses propres conditions.

Formats des valeurs :

• Dates. Toute date ou date-heure ISO 8601, comme 2026-09-01 ou 2026-09-01T14:30:00Z. before et after sont exclusifs.
• Booléens. true ou 1 signifient vrai. Toute autre valeur signifie faux.
• Énumérations. L’une des valeurs listées pour la clé ci-dessous.
• empty et not_empty. La valeur est ignorée, mais le paramètre en exige une. Utilisez 1, par exemple spam_score.empty=1.

Exemples

E-mails rebondis ou en échec depuis le 1er septembre :

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

Comme match=or s’applique à tous les filtres de la requête, vous ne pouvez pas mélanger ET et OU. Pour combiner une plage de dates avec plusieurs statuts possibles sur Lister les e-mails, utilisez comme ci-dessus le paramètre dédié date_from pour la date : les paramètres dédiés s’appliquent toujours en ET.

Contacts d’Acme dont le champ personnalisé plan vaut pro, triés par adresse e-mail :

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

Domaines dont l’enregistrement DKIM est en erreur, du plus ancien au plus récent :

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

Encodage d’URL

Encodez les caractères réservés dans les valeurs : + en %2B, & en %26, # en %23, l’espace en %20 et @ en %40. Un + non encodé dans une adresse comme ada+news@example.com est lu comme un espace. Avec cURL, -G et --data-urlencode se chargent de l’encodage pour vous :

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

Champs filtrables

Sauf mention contraire, chaque clé de ces tableaux est aussi une clé de tri.

E-mails

Lister les e-mails (GET /emails).

Accepte aussi search, type (outbound ou inbound), date_from et date_to, ainsi que les anciens paramètres status, rcpt_to, mail_from, subject, api_key_id et sending_domain_id.

Domaines

Lister les domaines (GET /domains).

Accepte aussi search (le nom de domaine contient la valeur).

Clés API

Lister les clés API (GET /api-keys).

Accepte aussi search (le nom contient la valeur).

Listes de contacts et abonnés

Lister les listes de contacts (GET /audiences) accepte name (string) et created_at (date), ainsi que search.

Lister les abonnés (GET /audiences/{id}/subscribers) :

Accepte aussi search (l’adresse e-mail, le prénom ou le nom contient la valeur) et subscribed=true|false.

Contacts

Lister les contacts (GET /contacts) et Exporter des contacts.

Triez les contacts avec sort défini sur email, first_name, last_name, name, audiences, created_at ou updated_at, et order défini sur asc ou desc. Accepte aussi search (alias q), audience_id et unsubscribed. Les anciennes formes filter[audience_id], filter[unsubscribed] et filter[custom_fields][<key>] fonctionnent toujours.

Campagnes

Lister les campagnes (GET /campaigns).

Accepte aussi search (le nom ou l’objet contient la valeur).

Formulaires

Lister les formulaires (GET /forms).

Accepte aussi search (le nom contient la valeur).

Automatisations

Lister les automatisations (GET /automations).

Triez avec sort défini sur name, created_at, updated_at ou last_triggered_at, et order défini sur asc ou desc. Accepte aussi filter[name], filter[status] et filter[context].

Lister les exécutions (GET /automations/{id}/runs) accepte status (string), event (string) et created_at (date).

Modèles

Lister les modèles (GET /templates). Seules les versions publiées sont listées.

Triez avec sort défini sur name, alias, created_at, updated_at ou published_at, et order défini sur asc ou desc. Accepte aussi filter[name], filter[alias] et filter[editor].

Adresses bloquées

Lister les adresses bloquées (GET /suppressions).

Triez avec sort défini sur email, reason, type ou created_at, et order défini sur asc ou desc. Accepte aussi search (alias q ; l’adresse e-mail ou le motif contient la valeur).

La liste des adresses bloquées accepte aussi un générateur de filtres JSON dans le paramètre filters (alias filter). Transmettez un objet JSON encodé pour l’URL :

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

Événements

Lister les événements (GET /events).

Accepte aussi type sous forme de liste de types d’événements exacts séparés par des virgules, ainsi que include_data.

Webhooks

Lister les webhooks (GET /webhooks).

Accepte aussi search (le nom ou l’URL contient la valeur).

Listes de vérification d’e-mails

Lister les listes (GET /email-verification-lists) accepte name (string), status (string) et created_at (date), ainsi que search et status.

Lister les résultats (GET /email-verification-lists/{id}/results) :

Accepte aussi status et result.

Rapports DMARC

Lister les rapports agrégés et Lister les rapports forensiques.

Accepte aussi type, status, org_name, from et to. Les listes DMARC se paginent avec limit et offset. Consultez Pagination.

Voir aussi