# Filtri e ordinamento

> Filtra e ordina gli endpoint di elenco dell’API con i parametri di query key.condition=value, match e order. Tutte le condizioni e i campi filtrabili di ogni risorsa.

Gli endpoint di elenco accettano nella query string lo stesso linguaggio di filtri a un solo livello: un parametro di query per ogni filtro, combinati con `match` e ordinati con `order` e `direction`. Questa pagina descrive la sintassi, le condizioni per ogni tipo di campo e tutti i campi su cui puoi filtrare e ordinare, risorsa per risorsa.

## Sintassi

Un filtro è un parametro di query chiamato `<key>.<condition>` con il valore con cui confrontare:

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

| Parametro | Descrizione |
| --- | --- |
| `<key>.<condition>=<value>` | Un filtro. Aggiungine quanti te ne servono, anche più di uno sulla stessa chiave. |
| `match` | Come si combinano i filtri. `all` (predefinito) restituisce le righe che corrispondono a tutti i filtri. `or` restituisce le righe che corrispondono ad almeno un filtro. |
| `order` | La chiave per cui ordinare. Deve essere una delle chiavi di ordinamento dell’endpoint. |
| `direction` | `asc` o `desc`. Se passi `order` senza `direction`, i risultati vengono ordinati in modo crescente. |

Senza `order`, gli elenchi restituiscono prima gli oggetti più recenti.

I filtri vengono combinati in AND con gli eventuali parametri dedicati dell’endpoint, come `search` o `type`. `match` controlla solo come si combinano tra loro i filtri `key.condition`.

Le chiavi sconosciute, le condizioni non adatte al tipo della chiave e i valori non interpretabili (una data non valida, un valore non numerico, un valore enum inesistente o un valore vuoto) vengono ignorati invece che rifiutati. Se un filtro sembra non avere effetto, controlla di averlo scritto correttamente.

### Vecchi parametri di ordinamento

Alcuni endpoint accettano anche `sort=<key>` con `order=asc` o `order=desc`. In [Elenca i contatti](/it/docs/api-reference/contacts/list/), [Elenca i template](/it/docs/api-reference/templates/list/), [Elenca le automazioni](/it/docs/api-reference/automations/list/) ed [Elenca le soppressioni](/it/docs/api-reference/suppressions/list/), `order` accetta solo `asc` o `desc`, quindi ordina questi elenchi con `sort=<key>&order=<direction>` invece di `order=<key>`. La vecchia forma funziona su tutti gli endpoint di elenco.

## Condizioni

Ogni chiave ha un tipo, e ogni tipo accetta le proprie condizioni.

| Condizione | String | Number | Date | Boolean | Enum | Corrisponde quando il campo… |
| --- | --- | --- | --- | --- | --- | --- |
| `exact` | Sì | Sì | Sì | Sì | Sì | è uguale al valore. Le stringhe vengono confrontate distinguendo tra maiuscole e minuscole. Per le date viene confrontato il giorno di calendario. |
| `not_exact` | Sì | Sì |  | Sì | Sì | è diverso dal valore. |
| `contains` | Sì |  |  |  |  | contiene il valore, senza distinzione tra maiuscole e minuscole. |
| `not_contains` | Sì |  |  |  |  | non contiene il valore, senza distinzione tra maiuscole e minuscole. Corrispondono anche i campi vuoti. |
| `starts_with` | Sì |  |  |  |  | inizia con il valore, senza distinzione tra maiuscole e minuscole. |
| `ends_with` | Sì |  |  |  |  | finisce con il valore, senza distinzione tra maiuscole e minuscole. |
| `gt`, `gte` | | Sì |  |  |  | è maggiore del valore (o uguale). |
| `lt`, `lte` | | Sì |  |  |  | è minore del valore (o uguale). |
| `before` |  |  | Sì |  |  | è precedente al valore. |
| `after` |  |  | Sì |  |  | è successivo al valore. |
| `empty` | Sì | Sì | Sì |  |  | non ha un valore. Per le stringhe, anche una stringa vuota conta come vuota. |
| `not_empty` | Sì | Sì | Sì |  |  | ha un valore. |

Formati dei valori:

- **Date.** Qualsiasi data o data e ora ISO 8601, ad esempio `2026-09-01` o `2026-09-01T14:30:00Z`. `before` e `after` sono esclusivi.
- **Booleani.** `true` o `1` significano vero. Qualsiasi altro valore significa falso.
- **Enum.** Uno dei valori elencati per la chiave qui sotto.
- **`empty` e `not_empty`.** Il valore viene ignorato, ma il parametro ne richiede uno. Usa `1`, ad esempio `spam_score.empty=1`.

## Esempi

Email rimbalzate o non riuscite dal 1° settembre:

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

Poiché `match=or` si applica a tutti i filtri della richiesta, non puoi combinare AND e OR. Per combinare un intervallo di date con stati alternativi in [Elenca le email](/it/docs/api-reference/emails/list/), usa per la data il parametro dedicato `date_from`, come nell’esempio, perché i parametri dedicati si applicano sempre in AND.

Contatti di Acme il cui campo personalizzato `plan` è `pro`, ordinati per email:

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

Domini con un record DKIM non corretto, a partire dal meno recente:

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

### Codifica URL

Codifica i caratteri riservati nei valori: `+` come `%2B`, `&` come `%26`, `#` come `%23`, lo spazio come `%20` e `@` come `%40`. Un `+` non codificato in un indirizzo come `ada+news@example.com` viene letto come uno spazio. Con cURL, `-G` e `--data-urlencode` si occupano della codifica al posto tuo:

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

## Campi filtrabili

Salvo diversa indicazione nelle note, ogni chiave di queste tabelle è anche una chiave di ordinamento.

### Email

[Elenca le email](/it/docs/api-reference/emails/list/) (`GET /emails`).

| Chiave | Tipo | Note |
| --- | --- | --- |
| `to` | string | Indirizzo del destinatario. |
| `from` | string | Mittente così come è stato inviato, compreso l’eventuale nome visualizzato. |
| `subject` | string | |
| `status` | enum | `accepted`, `scheduled`, `delivered`, `loaded`, `clicked`, `attempted`, `bounced`, `failed`, `rejected`, `suppressed`, `received`, `complained`, `canceled`, `held` |
| `tag` | string | Il tag dell’email. Al momento l’invio tramite API o SMTP non imposta alcun tag. |
| `spam_score` | number | |
| `created_at` | date | Non allarga l’intervallo predefinito di 14 giorni. Per le email più vecchie usa `date_from`. |
| `updated_at` | date | |
| `api_key_id` | string | L’ID `key_…` della chiave API che ha inviato l’email. |
| `sending_domain_id` | string | L’ID `dom_…` del dominio di invio. |

Accetta anche `search`, `type` (`outbound` o `inbound`), `date_from` e `date_to`, oltre ai vecchi parametri `status`, `rcpt_to`, `mail_from`, `subject`, `api_key_id` e `sending_domain_id`.

### Domini

[Elenca i domini](/it/docs/api-reference/domains/list/) (`GET /domains`).

| Chiave | Tipo | Note |
| --- | --- | --- |
| `name` | string | |
| `created_at` | date | |
| `spf_status` | enum | `ok`, `missing`, `invalid` |
| `dkim_status` | enum | `ok`, `missing`, `invalid` |
| `return_path_status` | enum | `ok`, `missing`, `invalid` |

Accetta anche `search` (il nome del dominio contiene).

### Chiavi API

[Elenca le chiavi API](/it/docs/api-reference/api-keys/list/) (`GET /api-keys`).

| Chiave | Tipo | Note |
| --- | --- | --- |
| `name` | string | |
| `scope` | string | `full` o `sending`. |
| `type` | string | Tipo di credenziale. Le chiavi create nel pannello o con l’API sono `api`. |
| `created_at` | date | |

Accetta anche `search` (il nome contiene).

### Liste e iscritti

[Elenca le liste](/it/docs/api-reference/audiences/list/) (`GET /audiences`) accetta `name` (string) e `created_at` (date), oltre a `search`.

[Elenca gli iscritti](/it/docs/api-reference/audiences/subscribers/list/) (`GET /audiences/{id}/subscribers`):

| Chiave | Tipo | Note |
| --- | --- | --- |
| `email` | string | L’indirizzo email del contatto. |
| `first_name` | string | |
| `last_name` | string | |
| `subscribed` | boolean | |
| `created_at` | date | Quando il contatto è entrato nella lista. |

Accetta anche `search` (l’email, il nome o il cognome contiene) e `subscribed=true|false`.

### Contatti

[Elenca i contatti](/it/docs/api-reference/contacts/list/) (`GET /contacts`) ed [Esporta i contatti](/it/docs/api-reference/contacts/export/).

| Chiave | Tipo | Note |
| --- | --- | --- |
| `email` | string | |
| `first_name` | string | |
| `last_name` | string | |
| `name` | string | Nome e cognome uniti da uno spazio. |
| `audiences` | string | Il nome della prima lista del contatto in ordine alfabetico. |
| `unsubscribed` | boolean | Solo come filtro. |
| `created_at` | date | |
| `updated_at` | date | |
| `audience_id` | string | Solo come filtro. Solo `exact` e `not_exact`. Il valore è un ID di lista (`aud_…`). |
| `custom_fields.<key>` | string | Solo come filtro. Sostituisci `<key>` con la chiave del campo personalizzato, ad esempio `custom_fields.company.contains=Acme`. I valori vengono confrontati come testo. |

Ordina i contatti con `sort` impostato su `email`, `first_name`, `last_name`, `name`, `audiences`, `created_at` o `updated_at`, e `order` impostato su `asc` o `desc`. Accetta anche `search` (alias `q`), `audience_id` e `unsubscribed`. Le vecchie forme `filter[audience_id]`, `filter[unsubscribed]` e `filter[custom_fields][<key>]` funzionano ancora.

### Campagne

[Elenca le campagne](/it/docs/api-reference/campaigns/list/) (`GET /campaigns`).

| Chiave | Tipo | Note |
| --- | --- | --- |
| `name` | string | |
| `subject` | string | |
| `status` | enum | `draft`, `scheduled`, `queued`, `sending`, `sent`, `archived` |
| `created_at` | date | |
| `sent_at` | date | |

Accetta anche `search` (il nome o l’oggetto contiene).

### Moduli

[Elenca i moduli](/it/docs/api-reference/forms/list/) (`GET /forms`).

| Chiave | Tipo | Note |
| --- | --- | --- |
| `name` | string | |
| `type` | enum | `popup`, `full_page`, `flyout`, `embed`, `banner` |
| `status` | enum | `draft`, `live` |
| `created_at` | date | |

Accetta anche `search` (il nome contiene).

### Automazioni

[Elenca le automazioni](/it/docs/api-reference/automations/list/) (`GET /automations`).

| Chiave | Tipo | Note |
| --- | --- | --- |
| `name` | string | |
| `status` | enum | Solo come filtro. `draft`, `running`, `paused`, `stopped`, `archived` |
| `context` | string | Solo come filtro. `contact`, `email` o `event`. |
| `created_at` | date | |

Ordina con `sort` impostato su `name`, `created_at`, `updated_at` o `last_triggered_at`, e `order` impostato su `asc` o `desc`. Accetta anche `filter[name]`, `filter[status]` e `filter[context]`.

[Elenca le esecuzioni](/it/docs/api-reference/automations/runs/) (`GET /automations/{id}/runs`) accetta `status` (string), `event` (string) e `created_at` (date).

### Template

[Elenca i template](/it/docs/api-reference/templates/list/) (`GET /templates`). Vengono elencate solo le versioni pubblicate.

| Chiave | Tipo | Note |
| --- | --- | --- |
| `name` | string | |
| `alias` | string | |
| `editor` | string | Solo come filtro. `html`, `text`, `dragit` o `tiptap`. |
| `subject` | string | Solo come filtro. |
| `created_at` | date | |

Ordina con `sort` impostato su `name`, `alias`, `created_at`, `updated_at` o `published_at`, e `order` impostato su `asc` o `desc`. Accetta anche `filter[name]`, `filter[alias]` e `filter[editor]`.

### Soppressioni

[Elenca le soppressioni](/it/docs/api-reference/suppressions/list/) (`GET /suppressions`).

| Chiave | Tipo | Note |
| --- | --- | --- |
| `email` | string | |
| `reason` | string | |
| `type` | string | |
| `created_at` | date | |
| `keep_until` | date | Solo come filtro. |

Ordina con `sort` impostato su `email`, `reason`, `type` o `created_at`, e `order` impostato su `asc` o `desc`. Accetta anche `search` (alias `q`, l’email o il motivo contiene).

Le soppressioni accettano anche un generatore di filtri JSON nel parametro `filters` (alias `filter`). Passa un oggetto JSON codificato per l’URL:

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

| Proprietà | Descrizione |
| --- | --- |
| `match` | `all` (predefinito) o `any`. |
| `rules` | Fino a 25 regole. Le regole con un campo o un operatore sconosciuto vengono ignorate. |
| `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` | Il valore da confrontare. Per `in` e `not_in`, un elenco separato da virgole. Non serve per `is_set` e `is_not_set`. |

### Eventi

[Elenca gli eventi](/it/docs/api-reference/events/list/) (`GET /events`).

| Chiave | Tipo | Note |
| --- | --- | --- |
| `type` | string | Il tipo di evento, ad esempio `email.delivered`. |
| `created_at` | date | Qualsiasi filtro `created_at` sostituisce l’intervallo predefinito di due giorni. |

Accetta anche `type` come elenco separato da virgole di tipi di evento esatti, e `include_data`.

### Webhook

[Elenca i webhook](/it/docs/api-reference/webhooks/list/) (`GET /webhooks`).

| Chiave | Tipo | Note |
| --- | --- | --- |
| `name` | string | |
| `url` | string | |
| `enabled` | boolean | |
| `created_at` | date | |

Accetta anche `search` (il nome o l’URL contiene).

### Liste di verifica

[Elenca le liste](/it/docs/api-reference/email-verifications/lists/list/) (`GET /email-verification-lists`) accetta `name` (string), `status` (string) e `created_at` (date), oltre a `search` e `status`.

[Elenca gli esiti](/it/docs/api-reference/email-verifications/lists/results/) (`GET /email-verification-lists/{id}/results`):

| Chiave | Tipo | Note |
| --- | --- | --- |
| `email` | string | |
| `status` | string | |
| `result` | string | Ad esempio `safe`, `invalid` o `disposable`. |
| `risk` | string | `low`, `medium` o `high`. |
| `created_at` | date | |

Accetta anche `status` e `result`.

### Report DMARC

[Elenca i report aggregati](/it/docs/api-reference/dmarc/list/) ed [Elenca i report forensi](/it/docs/api-reference/dmarc/forensic/).

| Chiave | Tipo | Note |
| --- | --- | --- |
| `type` | string | `aggregate` o `forensic`. |
| `status` | string | |
| `org_name` | string | L’organizzazione che ha inviato il report. |
| `created_at` | date | Quando Emailit ha ricevuto il report. |

Accetta anche `type`, `status`, `org_name`, `from` e `to`. Gli elenchi DMARC usano la paginazione con `limit` e `offset`. Vedi [Paginazione](/it/docs/api-reference/pagination/).

## Vedi anche

  - [Paginazione](/it/docs/api-reference/pagination/): Scorri le pagine dei risultati degli elenchi.
  - [Tutti gli endpoint](/it/docs/api-reference/endpoints/): Tutti gli endpoint e il permesso che richiedono.

---
Fonte: https://emailit.com/it/docs/api-reference/filtering/