# Filtrage et tri

> Filtrez et triez les endpoints de liste de l’API avec des paramètres de requête key.condition=value, match et order. Toutes les conditions et tous les champs filtrables, par ressource.

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 :

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

| Paramètre | Description |
| --- | --- |
| `<key>.<condition>=<value>` | Un filtre. Ajoutez-en autant que nécessaire, y compris plusieurs sur la même clé. |
| `match` | Mode de combinaison des filtres. `all` (par défaut) renvoie les lignes qui correspondent à tous les filtres. `or` renvoie les lignes qui correspondent à au moins un filtre. |
| `order` | La clé de tri. Doit faire partie des clés de tri de l’endpoint. |
| `direction` | `asc` ou `desc`. Si vous transmettez `order` sans `direction`, les résultats sont triés par ordre croissant. |

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](/fr/docs/api-reference/contacts/list/), [Lister les modèles](/fr/docs/api-reference/templates/list/), [Lister les automatisations](/fr/docs/api-reference/automations/list/) et [Lister les adresses bloquées](/fr/docs/api-reference/suppressions/list/), `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.

| Condition | String | Number | Date | Boolean | Enum | Correspond quand le champ… |
| --- | --- | --- | --- | --- | --- | --- |
| `exact` | Oui | Oui | Oui | Oui | Oui | est égal à la valeur. Les chaînes sont comparées en respectant la casse. Les dates sont comparées au jour près. |
| `not_exact` | Oui | Oui |  | Oui | Oui | n’est pas égal à la valeur. |
| `contains` | Oui |  |  |  |  | contient la valeur, sans tenir compte de la casse. |
| `not_contains` | Oui |  |  |  |  | ne contient pas la valeur, sans tenir compte de la casse. Les champs vides correspondent. |
| `starts_with` | Oui |  |  |  |  | commence par la valeur, sans tenir compte de la casse. |
| `ends_with` | Oui |  |  |  |  | se termine par la valeur, sans tenir compte de la casse. |
| `gt`, `gte` | | Oui |  |  |  | est supérieur (ou égal) à la valeur. |
| `lt`, `lte` | | Oui |  |  |  | est inférieur (ou égal) à la valeur. |
| `before` |  |  | Oui |  |  | est antérieur à la valeur. |
| `after` |  |  | Oui |  |  | est postérieur à la valeur. |
| `empty` | Oui | Oui | Oui |  |  | n’a pas de valeur. Pour les chaînes, une chaîne vide compte comme vide. |
| `not_empty` | Oui | Oui | Oui |  |  | a une valeur. |

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 :

```text
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](/fr/docs/api-reference/emails/list/), 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 :

```text
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 :

```text
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**

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

## Champs filtrables

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

### E-mails

[Lister les e-mails](/fr/docs/api-reference/emails/list/) (`GET /emails`).

| Clé | Type | Remarques |
| --- | --- | --- |
| `to` | string | Adresse du destinataire. |
| `from` | string | Expéditeur tel qu’envoyé, avec son éventuel nom d’affichage. |
| `subject` | string | |
| `status` | enum | `accepted`, `scheduled`, `delivered`, `loaded`, `clicked`, `attempted`, `bounced`, `failed`, `rejected`, `suppressed`, `received`, `complained`, `canceled`, `held` |
| `tag` | string | Le tag de l’e-mail. Les envois via l’API ou SMTP ne définissent pas de tag pour le moment. |
| `spam_score` | number | |
| `created_at` | date | N’élargit pas la fenêtre par défaut de 14 jours. Utilisez `date_from` pour les e-mails plus anciens. |
| `updated_at` | date | |
| `api_key_id` | string | L’ID `key_…` de la clé API qui a envoyé l’e-mail. |
| `sending_domain_id` | string | L’ID `dom_…` du domaine d’envoi. |

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](/fr/docs/api-reference/domains/list/) (`GET /domains`).

| Clé | Type | Remarques |
| --- | --- | --- |
| `name` | string | |
| `created_at` | date | |
| `spf_status` | enum | `ok`, `missing`, `invalid` |
| `dkim_status` | enum | `ok`, `missing`, `invalid` |
| `return_path_status` | enum | `ok`, `missing`, `invalid` |

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

### Clés API

[Lister les clés API](/fr/docs/api-reference/api-keys/list/) (`GET /api-keys`).

| Clé | Type | Remarques |
| --- | --- | --- |
| `name` | string | |
| `scope` | string | `full` ou `sending`. |
| `type` | string | Type d’identifiant. Les clés créées dans le tableau de bord ou via l’API sont de type `api`. |
| `created_at` | date | |

Accepte aussi `search` (le nom contient la valeur).

### Listes de contacts et abonnés

[Lister les listes de contacts](/fr/docs/api-reference/audiences/list/) (`GET /audiences`) accepte `name` (string) et `created_at` (date), ainsi que `search`.

[Lister les abonnés](/fr/docs/api-reference/audiences/subscribers/list/) (`GET /audiences/{id}/subscribers`) :

| Clé | Type | Remarques |
| --- | --- | --- |
| `email` | string | L’adresse e-mail du contact. |
| `first_name` | string | |
| `last_name` | string | |
| `subscribed` | boolean | |
| `created_at` | date | Date à laquelle le contact a rejoint la liste. |

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

### Contacts

[Lister les contacts](/fr/docs/api-reference/contacts/list/) (`GET /contacts`) et [Exporter des contacts](/fr/docs/api-reference/contacts/export/).

| Clé | Type | Remarques |
| --- | --- | --- |
| `email` | string | |
| `first_name` | string | |
| `last_name` | string | |
| `name` | string | Prénom et nom réunis, séparés par un espace. |
| `audiences` | string | Le nom de la première liste du contact dans l’ordre alphabétique. |
| `unsubscribed` | boolean | Filtre uniquement. |
| `created_at` | date | |
| `updated_at` | date | |
| `audience_id` | string | Filtre uniquement. Seulement `exact` et `not_exact`. La valeur est un ID de liste (`aud_…`). |
| `custom_fields.<key>` | string | Filtre uniquement. Remplacez `<key>` par la clé du champ personnalisé, par exemple `custom_fields.company.contains=Acme`. Les valeurs sont comparées comme du texte. |

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](/fr/docs/api-reference/campaigns/list/) (`GET /campaigns`).

| Clé | Type | Remarques |
| --- | --- | --- |
| `name` | string | |
| `subject` | string | |
| `status` | enum | `draft`, `scheduled`, `queued`, `sending`, `sent`, `archived` |
| `created_at` | date | |
| `sent_at` | date | |

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

### Formulaires

[Lister les formulaires](/fr/docs/api-reference/forms/list/) (`GET /forms`).

| Clé | Type | Remarques |
| --- | --- | --- |
| `name` | string | |
| `type` | enum | `popup`, `full_page`, `flyout`, `embed`, `banner` |
| `status` | enum | `draft`, `live` |
| `created_at` | date | |

Accepte aussi `search` (le nom contient la valeur).

### Automatisations

[Lister les automatisations](/fr/docs/api-reference/automations/list/) (`GET /automations`).

| Clé | Type | Remarques |
| --- | --- | --- |
| `name` | string | |
| `status` | enum | Filtre uniquement. `draft`, `running`, `paused`, `stopped`, `archived` |
| `context` | string | Filtre uniquement. `contact`, `email` ou `event`. |
| `created_at` | date | |

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](/fr/docs/api-reference/automations/runs/) (`GET /automations/{id}/runs`) accepte `status` (string), `event` (string) et `created_at` (date).

### Modèles

[Lister les modèles](/fr/docs/api-reference/templates/list/) (`GET /templates`). Seules les versions publiées sont listées.

| Clé | Type | Remarques |
| --- | --- | --- |
| `name` | string | |
| `alias` | string | |
| `editor` | string | Filtre uniquement. `html`, `text`, `dragit` ou `tiptap`. |
| `subject` | string | Filtre uniquement. |
| `created_at` | date | |

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](/fr/docs/api-reference/suppressions/list/) (`GET /suppressions`).

| Clé | Type | Remarques |
| --- | --- | --- |
| `email` | string | |
| `reason` | string | |
| `type` | string | |
| `created_at` | date | |
| `keep_until` | date | Filtre uniquement. |

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 :

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

| Propriété | Description |
| --- | --- |
| `match` | `all` (par défaut) ou `any`. |
| `rules` | 25 règles au maximum. Les règles dont le champ ou l’opérateur est inconnu sont ignorées. |
| `rules[].field` | `email`, `reason`, `type` ou `created_at`. |
| `rules[].operator` | `equals`, `not_equals`, `contains`, `not_contains`, `starts_with`, `ends_with`, `greater_than`, `less_than`, `in`, `not_in`, `is_set` ou `is_not_set`. |
| `rules[].value` | La valeur à comparer. Pour `in` et `not_in`, une liste séparée par des virgules. Inutile pour `is_set` et `is_not_set`. |

### Événements

[Lister les événements](/fr/docs/api-reference/events/list/) (`GET /events`).

| Clé | Type | Remarques |
| --- | --- | --- |
| `type` | string | Le type d’événement, comme `email.delivered`. |
| `created_at` | date | Tout filtre `created_at` remplace la fenêtre par défaut de deux jours. |

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](/fr/docs/api-reference/webhooks/list/) (`GET /webhooks`).

| Clé | Type | Remarques |
| --- | --- | --- |
| `name` | string | |
| `url` | string | |
| `enabled` | boolean | |
| `created_at` | date | |

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

### Listes de vérification d’e-mails

[Lister les listes](/fr/docs/api-reference/email-verifications/lists/list/) (`GET /email-verification-lists`) accepte `name` (string), `status` (string) et `created_at` (date), ainsi que `search` et `status`.

[Lister les résultats](/fr/docs/api-reference/email-verifications/lists/results/) (`GET /email-verification-lists/{id}/results`) :

| Clé | Type | Remarques |
| --- | --- | --- |
| `email` | string | |
| `status` | string | |
| `result` | string | Par exemple `safe`, `invalid` ou `disposable`. |
| `risk` | string | `low`, `medium` ou `high`. |
| `created_at` | date | |

Accepte aussi `status` et `result`.

### Rapports DMARC

[Lister les rapports agrégés](/fr/docs/api-reference/dmarc/list/) et [Lister les rapports forensiques](/fr/docs/api-reference/dmarc/forensic/).

| Clé | Type | Remarques |
| --- | --- | --- |
| `type` | string | `aggregate` ou `forensic`. |
| `status` | string | |
| `org_name` | string | L’organisation qui a envoyé le rapport. |
| `created_at` | date | Date de réception du rapport par Emailit. |

Accepte aussi `type`, `status`, `org_name`, `from` et `to`. Les listes DMARC se paginent avec `limit` et `offset`. Consultez [Pagination](/fr/docs/api-reference/pagination/).

## Voir aussi

  - [Pagination](/fr/docs/api-reference/pagination/): Parcourez les résultats d’une liste page par page.
  - [Tous les endpoints](/fr/docs/api-reference/endpoints/): Chaque endpoint et la portée qu’il nécessite.

---
Source: https://emailit.com/fr/docs/api-reference/filtering/