Vai al contenuto
Docs

Riferimento

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.

Aggiornato il 19 ott 2026

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, Elenca i template, Elenca le automazioni, Elenca le soppressioni, Elenca i prodotti ed Elenca gli ordini, 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, 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:

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

Campi filtrabili

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

Email

Elenca le email (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 (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 (GET /api-keys).

Chiave Tipo Note
name string
scope string full, sending o events.
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 (GET /audiences) accetta name (string) e created_at (date), oltre a search.

Elenca gli iscritti (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 (GET /contacts) ed Esporta i contatti.

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.

Segmenti

Elenca i segmenti (GET /segments) accetta name (string), created_at (date) e updated_at (date), più search. Elenca i contatti di un segmento accetta le chiavi dei contatti.

Campagne

Elenca le campagne (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).

Prodotti

Elenca i prodotti (GET /products).

Chiave Tipo Note
title string
external_id string L’ID del prodotto nel tuo negozio. Solo come filtro.
sku string Solo come filtro.
brand string Solo come filtro.
currency string Solo come filtro.
price number
inventory_quantity number Solo come filtro.
status enum Solo come filtro. active, archived. Senza il parametro status vengono elencati solo i prodotti attivi, quindi aggiungi status=all.
created_at date
updated_at date

Ordina con sort impostato su created_at, updated_at, title o price, e order impostato su asc o desc. Accetta anche search, category, status e ids.

Ordini

Elenca gli ordini (GET /orders).

Chiave Tipo Note
external_id string L’ID dell’ordine nel tuo negozio. Solo come filtro.
email string Solo come filtro.
status enum Solo come filtro. placed, paid, fulfilled, canceled, refunded
currency string Solo come filtro.
total number
source enum Solo come filtro. api, js, import, dashboard
attribution_type enum Solo come filtro. click, open
placed_at date
created_at date

Ordina con sort impostato su placed_at, total o created_at, e order impostato su asc o desc. Accetta anche search, contact_id, email, status, campaign_id, automation_id, attributed, from e to.

Carrelli e coupon

Elenca i carrelli (GET /carts):

Chiave Tipo Note
external_id string L’ID del carrello nel tuo negozio.
email string
status enum active, abandoned, converted
total number
currency string
updated_at date
abandoned_at date
created_at date

Accetta anche status e contact_id.

Elenca i coupon (GET /coupons) accetta key (string), name (string), kind (enum: unique, static), expires_at (date) e created_at (date), più search.

Elenca i codici di un coupon (GET /coupons/{id}/codes) accetta code (string), email (string), assigned_at (date), redeemed_at (date) e created_at (date), più status.

Moduli

Elenca i moduli (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 (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 (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.

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 (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 (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, scope (system, workspace o custom, separati da virgole) e include_data.

Eventi di workspace

Elenca gli eventi di workspace (GET /workspace/events).

Chiave Tipo Note
name string Il nome senza il prefisso w:.
title string
created_at date
updated_at date

Accetta anche search (il nome o il titolo contiene).

Chiavi di tracciamento

Elenca le chiavi di tracciamento (GET /tracking-keys).

Chiave Tipo Note
name string
enabled boolean
created_at date
last_used_at date

Accetta anche search (il nome contiene).

Webhook

Elenca i webhook (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 (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):

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 ed Elenca i report forensi.

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.

Scorri le pagine dei risultati degli elenchi.
Tutti gli endpoint e il permesso che richiedono.

Questa pagina ti è stata utile?

Grazie del feedback.

Grazie, leggiamo ogni messaggio.