# Filtrování a řazení

> Filtrujte a řaďte výpisy API přes parametry dotazu key.condition=value, match a order. Všechny podmínky a pole, podle kterých lze filtrovat, pro každý zdroj.

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

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

| Parametr | Popis |
| --- | --- |
| `<key>.<condition>=<value>` | Jeden filtr. Přidejte jich, kolik potřebujete, i několik na stejný klíč. |
| `match` | Jak se filtry kombinují. `all` (výchozí) vrací řádky, které odpovídají všem filtrům. `or` vrací řádky, které odpovídají alespoň jednomu. |
| `order` | Klíč, podle kterého se řadí. Musí to být jeden z klíčů řazení daného endpointu. |
| `direction` | `asc`, nebo `desc`. Pokud předáte `order` bez `direction`, výsledky se seřadí vzestupně. |

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ů](/cs/docs/api-reference/contacts/list/), [výpisu šablon](/cs/docs/api-reference/templates/list/), [výpisu automatizací](/cs/docs/api-reference/automations/list/) a [výpisu blokovaných adres](/cs/docs/api-reference/suppressions/list/) 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.

| Podmínka | String | Number | Date | Boolean | Enum | Shoda nastane, když pole… |
| --- | --- | --- | --- | --- | --- | --- |
| `exact` | Ano | Ano | Ano | Ano | Ano | se rovná hodnotě. Řetězce se porovnávají s ohledem na velikost písmen. U dat se porovnává kalendářní den. |
| `not_exact` | Ano | Ano |  | Ano | Ano | se nerovná hodnotě. |
| `contains` | Ano |  |  |  |  | obsahuje hodnotu, bez ohledu na velikost písmen. |
| `not_contains` | Ano |  |  |  |  | neobsahuje hodnotu, bez ohledu na velikost písmen. Prázdná pole odpovídají. |
| `starts_with` | Ano |  |  |  |  | začíná hodnotou, bez ohledu na velikost písmen. |
| `ends_with` | Ano |  |  |  |  | končí hodnotou, bez ohledu na velikost písmen. |
| `gt`, `gte` | | Ano |  |  |  | je větší než hodnota (nebo rovno). |
| `lt`, `lte` | | Ano |  |  |  | je menší než hodnota (nebo rovno). |
| `before` |  |  | Ano |  |  | je dřívější než hodnota. |
| `after` |  |  | Ano |  |  | je pozdější než hodnota. |
| `empty` | Ano | Ano | Ano |  |  | nemá hodnotu. U řetězců se jako prázdný počítá i prázdný řetězec. |
| `not_empty` | Ano | Ano | Ano |  |  | má hodnotu. |

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áří:

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

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

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

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

## 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ů](/cs/docs/api-reference/emails/list/) (`GET /emails`).

| Klíč | Typ | Poznámky |
| --- | --- | --- |
| `to` | string | Adresa příjemce. |
| `from` | string | Odesílatel tak, jak byl odeslán, včetně případného zobrazovaného jména. |
| `subject` | string | |
| `status` | enum | `accepted`, `scheduled`, `delivered`, `loaded`, `clicked`, `attempted`, `bounced`, `failed`, `rejected`, `suppressed`, `received`, `complained`, `canceled`, `held` |
| `tag` | string | Štítek e-mailu. Odesílání přes API nebo SMTP zatím štítek nenastavuje. |
| `spam_score` | number | |
| `created_at` | date | Nerozšiřuje výchozí období 14 dní. Pro starší e-maily použijte `date_from`. |
| `updated_at` | date | |
| `api_key_id` | string | ID `key_…` API klíče, kterým byl e-mail odeslán. |
| `sending_domain_id` | string | ID `dom_…` odesílací domény. |

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

| Klíč | Typ | Poznámky |
| --- | --- | --- |
| `name` | string | |
| `created_at` | date | |
| `spf_status` | enum | `ok`, `missing`, `invalid` |
| `dkim_status` | enum | `ok`, `missing`, `invalid` |
| `return_path_status` | enum | `ok`, `missing`, `invalid` |

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

### API klíče

[Výpis API klíčů](/cs/docs/api-reference/api-keys/list/) (`GET /api-keys`).

| Klíč | Typ | Poznámky |
| --- | --- | --- |
| `name` | string | |
| `scope` | string | `full`, nebo `sending`. |
| `type` | string | Typ přístupového údaje. Klíče vytvořené ve webovém rozhraní nebo přes API mají hodnotu `api`. |
| `created_at` | date | |

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

### Seznamy kontaktů a odběratelé

[Výpis seznamů kontaktů](/cs/docs/api-reference/audiences/list/) (`GET /audiences`) přijímá `name` (string) a `created_at` (date) a navíc `search`.

[Výpis odběratelů](/cs/docs/api-reference/audiences/subscribers/list/) (`GET /audiences/{id}/subscribers`):

| Klíč | Typ | Poznámky |
| --- | --- | --- |
| `email` | string | E-mailová adresa kontaktu. |
| `first_name` | string | |
| `last_name` | string | |
| `subscribed` | boolean | |
| `created_at` | date | Kdy se kontakt přidal do seznamu. |

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

### Kontakty

[Výpis kontaktů](/cs/docs/api-reference/contacts/list/) (`GET /contacts`) a [Export kontaktů](/cs/docs/api-reference/contacts/export/).

| Klíč | Typ | Poznámky |
| --- | --- | --- |
| `email` | string | |
| `first_name` | string | |
| `last_name` | string | |
| `name` | string | Jméno a příjmení spojené mezerou. |
| `audiences` | string | Abecedně první název seznamu kontaktů, ve kterém kontakt je. |
| `unsubscribed` | boolean | Jen pro filtrování. |
| `created_at` | date | |
| `updated_at` | date | |
| `audience_id` | string | Jen pro filtrování. Jen `exact` a `not_exact`. Hodnota je ID seznamu kontaktů (`aud_…`). |
| `custom_fields.<key>` | string | Jen pro filtrování. Místo `<key>` uveďte klíč vlastního pole, například `custom_fields.company.contains=Acme`. Hodnoty se porovnávají jako text. |

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

| Klíč | Typ | Poznámky |
| --- | --- | --- |
| `name` | string | |
| `subject` | string | |
| `status` | enum | `draft`, `scheduled`, `queued`, `sending`, `sent`, `archived` |
| `created_at` | date | |
| `sent_at` | date | |

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

### Formuláře

[Výpis formulářů](/cs/docs/api-reference/forms/list/) (`GET /forms`).

| Klíč | Typ | Poznámky |
| --- | --- | --- |
| `name` | string | |
| `type` | enum | `popup`, `full_page`, `flyout`, `embed`, `banner` |
| `status` | enum | `draft`, `live` |
| `created_at` | date | |

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

### Automatizace

[Výpis automatizací](/cs/docs/api-reference/automations/list/) (`GET /automations`).

| Klíč | Typ | Poznámky |
| --- | --- | --- |
| `name` | string | |
| `status` | enum | Jen pro filtrování. `draft`, `running`, `paused`, `stopped`, `archived` |
| `context` | string | Jen pro filtrování. `contact`, `email` nebo `event`. |
| `created_at` | date | |

Ř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í](/cs/docs/api-reference/automations/runs/) (`GET /automations/{id}/runs`) přijímá `status` (string), `event` (string) a `created_at` (date).

### Šablony

[Výpis šablon](/cs/docs/api-reference/templates/list/) (`GET /templates`). Vypisují se jen publikované verze.

| Klíč | Typ | Poznámky |
| --- | --- | --- |
| `name` | string | |
| `alias` | string | |
| `editor` | string | Jen pro filtrování. `html`, `text`, `dragit` nebo `tiptap`. |
| `subject` | string | Jen pro filtrování. |
| `created_at` | date | |

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

| Klíč | Typ | Poznámky |
| --- | --- | --- |
| `email` | string | |
| `reason` | string | |
| `type` | string | |
| `created_at` | date | |
| `keep_until` | date | Jen pro filtrování. |

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

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

| Vlastnost | Popis |
| --- | --- |
| `match` | `all` (výchozí), nebo `any`. |
| `rules` | Nejvýše 25 pravidel. Pravidla s neznámým polem nebo operátorem se ignorují. |
| `rules[].field` | `email`, `reason`, `type` nebo `created_at`. |
| `rules[].operator` | `equals`, `not_equals`, `contains`, `not_contains`, `starts_with`, `ends_with`, `greater_than`, `less_than`, `in`, `not_in`, `is_set` nebo `is_not_set`. |
| `rules[].value` | Hodnota k porovnání. Pro `in` a `not_in` seznam oddělený čárkami. Pro `is_set` a `is_not_set` není potřeba. |

### Události

[Výpis událostí](/cs/docs/api-reference/events/list/) (`GET /events`).

| Klíč | Typ | Poznámky |
| --- | --- | --- |
| `type` | string | Typ události, například `email.delivered`. |
| `created_at` | date | Jakýkoli filtr `created_at` nahradí výchozí dvoudenní období. |

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

### Webhooky

[Výpis webhooků](/cs/docs/api-reference/webhooks/list/) (`GET /webhooks`).

| Klíč | Typ | Poznámky |
| --- | --- | --- |
| `name` | string | |
| `url` | string | |
| `enabled` | boolean | |
| `created_at` | date | |

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

### Seznamy k ověření

[Výpis seznamů k ověření](/cs/docs/api-reference/email-verifications/lists/list/) (`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ů](/cs/docs/api-reference/email-verifications/lists/results/) (`GET /email-verification-lists/{id}/results`):

| Klíč | Typ | Poznámky |
| --- | --- | --- |
| `email` | string | |
| `status` | string | |
| `result` | string | Například `safe`, `invalid` nebo `disposable`. |
| `risk` | string | `low`, `medium` nebo `high`. |
| `created_at` | date | |

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

### DMARC reporty

[Výpis souhrnných reportů](/cs/docs/api-reference/dmarc/list/) a [Výpis forenzních reportů](/cs/docs/api-reference/dmarc/forensic/).

| Klíč | Typ | Poznámky |
| --- | --- | --- |
| `type` | string | `aggregate`, nebo `forensic`. |
| `status` | string | |
| `org_name` | string | Organizace, která report poslala. |
| `created_at` | date | Kdy Emailit report přijal. |

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í](/cs/docs/api-reference/pagination/).

## Související

  - [Stránkování](/cs/docs/api-reference/pagination/): Procházejte výsledky výpisů po stránkách.
  - [Všechny endpointy](/cs/docs/api-reference/endpoints/): Všechny endpointy a oprávnění, která potřebují.

---
Zdroj: https://emailit.com/cs/docs/api-reference/filtering/