Filtrování a řazení

Endpointy pro výpisy přijímají v řetězci dotazu stejný jednoduchý jazyk filtrů: jeden parametr dotazu na každý filtr, kombinace přes match a řazení přes order a direction. Tato stránka popisuje syntaxi, podmínky pro jednotlivé typy polí a všechna pole, podle kterých můžete filtrovat a řadit, zdroj po zdroji.

Syntaxe

Filtr je parametr dotazu s názvem <key>.<condition> a hodnotou, se kterou se porovnává:

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

Bez order vracejí výpisy nejnovější objekty jako první.

Filtry se s vyhrazenými parametry endpointu, například search nebo type, kombinují přes AND. match určuje jen to, jak se mezi sebou kombinují filtry key.condition.

Neznámé klíče, podmínky, které neodpovídají typu klíče, a hodnoty, které nelze zpracovat (neplatné datum, něco jiného než číslo, neexistující hodnota výčtu nebo prázdná hodnota), se ignorují, místo aby se požadavek odmítl. Pokud se zdá, že filtr nemá žádný účinek, zkontrolujte jeho zápis.

Starší parametry řazení

Některé endpointy přijímají také sort=<key> s order=asc, nebo order=desc. Ve výpisu kontaktů, výpisu šablon, výpisu automatizací a výpisu blokovaných adres přijímá order jen asc, nebo desc, takže tyto výpisy řaďte přes sort=<key>&order=<direction>, ne přes order=<key>. Starší zápis funguje u všech endpointů pro výpisy.

Podmínky

Každý klíč má typ a každý typ přijímá vlastní podmínky.

Formáty hodnot:

• Datumy. Jakékoli datum nebo datum a čas podle ISO 8601, například 2026-09-01 nebo 2026-09-01T14:30:00Z. before a after hraniční hodnotu nezahrnují.
• Logické hodnoty. true nebo 1 znamenají pravdu. Jakákoli jiná hodnota znamená nepravdu.
• Výčty. Jedna z hodnot uvedených u klíče níže.
• empty a not_empty. Hodnota se ignoruje, ale parametr nějakou potřebuje. Použijte 1, například spam_score.empty=1.

Příklady

Nedoručené nebo neúspěšné e-maily od 1. září:

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

Protože match=or platí pro všechny filtry v požadavku, nemůžete kombinovat AND a OR. Pokud chcete ve výpisu e-mailů spojit časové období s alternativními stavy, použijte pro datum vyhrazený parametr date_from jako v příkladu, protože vyhrazené parametry se vždy uplatní přes AND.

Kontakty z Acme, jejichž vlastní pole plan má hodnotu pro, seřazené podle e-mailu:

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

Domény s chybným DKIM záznamem, od nejstarších:

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

Kódování URL

Vyhrazené znaky v hodnotách zakódujte: + jako %2B, & jako %26, # jako %23, mezeru jako %20 a @ jako %40. Nezakódované + v adrese jako ada+news@example.com se přečte jako mezera. V cURL se o kódování postarají -G a --data-urlencode:

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

Pole pro filtrování

Pokud poznámka neříká jinak, lze podle každého klíče v těchto tabulkách také řadit.

E-maily

Výpis e-mailů (GET /emails).

Přijímá také search, type (outbound, nebo inbound), date_from a date_to a navíc starší parametry status, rcpt_to, mail_from, subject, api_key_id a sending_domain_id.

Domény

Výpis domén (GET /domains).

Přijímá také search (název domény obsahuje).

API klíče

Výpis API klíčů (GET /api-keys).

Přijímá také search (název obsahuje).

Seznamy kontaktů a odběratelé

Výpis seznamů kontaktů (GET /audiences) přijímá name (string) a created_at (date) a navíc search.

Výpis odběratelů (GET /audiences/{id}/subscribers):

Přijímá také search (e-mail, jméno nebo příjmení obsahuje) a subscribed=true|false.

Kontakty

Výpis kontaktů (GET /contacts) a Export kontaktů.

Kontakty řaďte přes sort s hodnotou email, first_name, last_name, name, audiences, created_at nebo updated_at a order s hodnotou asc, nebo desc. Přijímá také search (alias q), audience_id a unsubscribed. Starší zápisy filter[audience_id], filter[unsubscribed] a filter[custom_fields][<key>] stále fungují.

Kampaně

Výpis kampaní (GET /campaigns).

Přijímá také search (název nebo předmět obsahuje).

Formuláře

Výpis formulářů (GET /forms).

Přijímá také search (název obsahuje).

Automatizace

Výpis automatizací (GET /automations).

Řaďte přes sort s hodnotou name, created_at, updated_at nebo last_triggered_at a order s hodnotou asc, nebo desc. Přijímá také filter[name], filter[status] a filter[context].

Výpis spuštění (GET /automations/{id}/runs) přijímá status (string), event (string) a created_at (date).

Šablony

Výpis šablon (GET /templates). Vypisují se jen publikované verze.

Řaďte přes sort s hodnotou name, alias, created_at, updated_at nebo published_at a order s hodnotou asc, nebo desc. Přijímá také filter[name], filter[alias] a filter[editor].

Blokované adresy

Výpis blokovaných adres (GET /suppressions).

Řaďte přes sort s hodnotou email, reason, type nebo created_at a order s hodnotou asc, nebo desc. Přijímá také search (alias q, e-mail nebo důvod obsahuje).

Blokované adresy přijímají v parametru filters (alias filter) také filtr sestavený jako JSON. Předejte objekt JSON zakódovaný do URL:

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

Události

Výpis událostí (GET /events).

Přijímá také type jako seznam přesných typů událostí oddělených čárkami a include_data.

Webhooky

Výpis webhooků (GET /webhooks).

Přijímá také search (název nebo URL obsahuje).

Seznamy k ověření

Výpis seznamů k ověření (GET /email-verification-lists) přijímá name (string), status (string) a created_at (date) a navíc search a status.

Výpis výsledků (GET /email-verification-lists/{id}/results):

Přijímá také status a result.

DMARC reporty

Výpis souhrnných reportů a Výpis forenzních reportů.

Přijímá také type, status, org_name, from a to. Výpisy DMARC se stránkují přes limit a offset. Viz Stránkování.

Související