Filtri e ordinamento

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:

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

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, Elenca i template, Elenca le automazioni ed Elenca le soppressioni, 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.

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:

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

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:

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

Campi filtrabili

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

Email

Elenca le email (GET /emails).

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

Accetta anche search (il nome del dominio contiene).

Chiavi API

Elenca le chiavi API (GET /api-keys).

Accetta anche search (il nome contiene).

Liste e iscritti

Elenca le liste (GET /audiences) accetta name (string) e created_at (date), oltre a search.

Elenca gli iscritti (GET /audiences/{id}/subscribers):

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

Contatti

Elenca i contatti (GET /contacts) ed Esporta i contatti.

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

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

Moduli

Elenca i moduli (GET /forms).

Accetta anche search (il nome contiene).

Automazioni

Elenca le automazioni (GET /automations).

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 (GET /automations/{id}/runs) accetta status (string), event (string) e created_at (date).

Template

Elenca i template (GET /templates). Vengono elencate solo le versioni pubblicate.

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

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:

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

Eventi

Elenca gli eventi (GET /events).

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

Webhook

Elenca i webhook (GET /webhooks).

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

Liste di verifica

Elenca le liste (GET /email-verification-lists) accetta name (string), status (string) e created_at (date), oltre a search e status.

Elenca gli esiti (GET /email-verification-lists/{id}/results):

Accetta anche status e result.

Report DMARC

Elenca i report aggregati ed Elenca i report forensi.

Accetta anche type, status, org_name, from e to. Gli elenchi DMARC usano la paginazione con limit e offset. Vedi Paginazione.

Vedi anche