# Filtern und Sortieren

> Listen-Endpunkte der API mit Query-Parametern der Form key.condition=value sowie match und order filtern und sortieren. Alle Bedingungen und filterbaren Felder pro Ressource.

Listen-Endpunkte akzeptieren im Query-String dieselbe flache Filtersprache: ein Query-Parameter pro Filter, kombiniert mit `match` und sortiert mit `order` und `direction`. Diese Seite behandelt die Syntax, die Bedingungen für jeden Feldtyp und alle Felder, nach denen Sie filtern und sortieren können, Ressource für Ressource.

## Syntax

Ein Filter ist ein Query-Parameter mit dem Namen `<key>.<condition>`, dessen Wert der Vergleichswert ist:

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

| Parameter | Beschreibung |
| --- | --- |
| `<key>.<condition>=<value>` | Ein Filter. Fügen Sie so viele hinzu wie nötig, auch mehrere für denselben Schlüssel. |
| `match` | Wie Filter kombiniert werden. `all` (Standardwert) gibt Zeilen zurück, die alle Filter erfüllen. `or` gibt Zeilen zurück, die mindestens einen erfüllen. |
| `order` | Der Schlüssel, nach dem sortiert wird. Muss einer der Sortierschlüssel des Endpunkts sein. |
| `direction` | `asc` oder `desc`. Wenn Sie `order` ohne `direction` übergeben, wird aufsteigend sortiert. |

Ohne `order` geben Listen die neuesten Objekte zuerst zurück.

Filter werden mit allen eigenen Parametern des Endpunkts, etwa `search` oder `type`, per AND verknüpft. `match` steuert nur, wie die Filter der Form `key.condition` untereinander kombiniert werden.

Unbekannte Schlüssel, Bedingungen, die nicht zum Typ des Schlüssels passen, und Werte, die sich nicht parsen lassen (ein ungültiges Datum, keine Zahl, ein nicht existierender Enum-Wert oder ein leerer Wert), werden ignoriert statt abgelehnt. Wenn ein Filter scheinbar keine Wirkung hat, prüfen Sie seine Schreibweise.

### Ältere Sortierparameter

Einige Endpunkte akzeptieren auch `sort=<key>` mit `order=asc` oder `order=desc`. Bei [Kontakte auflisten](/de/docs/api-reference/contacts/list/), [Vorlagen auflisten](/de/docs/api-reference/templates/list/), [Automatisierungen auflisten](/de/docs/api-reference/automations/list/) und [Sperrungen auflisten](/de/docs/api-reference/suppressions/list/) akzeptiert `order` nur `asc` oder `desc`. Sortieren Sie diese Listen deshalb mit `sort=<key>&order=<direction>` statt mit `order=<key>`. Die ältere Form funktioniert bei jedem Listen-Endpunkt.

## Bedingungen

Jeder Schlüssel hat einen Typ, und jeder Typ akzeptiert eigene Bedingungen.

| Bedingung | String | Zahl | Datum | Boolean | Enum | Trifft zu, wenn das Feld … |
| --- | --- | --- | --- | --- | --- | --- |
| `exact` | Ja | Ja | Ja | Ja | Ja | dem Wert entspricht. Strings werden mit Beachtung der Groß-/Kleinschreibung verglichen. Bei Datumswerten wird der Kalendertag verglichen. |
| `not_exact` | Ja | Ja |  | Ja | Ja | nicht dem Wert entspricht. |
| `contains` | Ja |  |  |  |  | den Wert enthält, ohne Beachtung der Groß-/Kleinschreibung. |
| `not_contains` | Ja |  |  |  |  | den Wert nicht enthält, ohne Beachtung der Groß-/Kleinschreibung. Leere Felder treffen zu. |
| `starts_with` | Ja |  |  |  |  | mit dem Wert beginnt, ohne Beachtung der Groß-/Kleinschreibung. |
| `ends_with` | Ja |  |  |  |  | mit dem Wert endet, ohne Beachtung der Groß-/Kleinschreibung. |
| `gt`, `gte` | | Ja |  |  |  | größer als der Wert (oder gleich) ist. |
| `lt`, `lte` | | Ja |  |  |  | kleiner als der Wert (oder gleich) ist. |
| `before` |  |  | Ja |  |  | vor dem Wert liegt. |
| `after` |  |  | Ja |  |  | nach dem Wert liegt. |
| `empty` | Ja | Ja | Ja |  |  | keinen Wert hat. Bei Strings gilt ein leerer String als leer. |
| `not_empty` | Ja | Ja | Ja |  |  | einen Wert hat. |

Wertformate:

- **Datumswerte.** Jedes Datum oder jeder Zeitpunkt nach ISO 8601, etwa `2026-09-01` oder `2026-09-01T14:30:00Z`. `before` und `after` schließen den Wert selbst aus.
- **Booleans.** `true` oder `1` bedeuten wahr. Jeder andere Wert bedeutet falsch.
- **Enums.** Einer der Werte, die unten für den Schlüssel aufgeführt sind.
- **`empty` und `not_empty`.** Der Wert wird ignoriert, aber der Parameter braucht einen. Verwenden Sie `1`, zum Beispiel `spam_score.empty=1`.

## Beispiele

Gebouncte oder fehlgeschlagene E-Mails seit dem 1. September:

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

Da `match=or` für alle Filter der Anfrage gilt, können Sie AND und OR nicht mischen. Um bei [E-Mails auflisten](/de/docs/api-reference/emails/list/) einen Zeitraum mit alternativen Status zu kombinieren, verwenden Sie für das Datum wie gezeigt den eigenen Parameter `date_from`, denn eigene Parameter gelten immer mit AND.

Kontakte bei Acme, deren eigenes Feld `plan` den Wert `pro` hat, sortiert nach E-Mail-Adresse:

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

Domains mit fehlerhaftem DKIM-Eintrag, älteste zuerst:

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

### URL-Kodierung

Kodieren Sie reservierte Zeichen in Werten: `+` als `%2B`, `&` als `%26`, `#` als `%23`, ein Leerzeichen als `%20` und `@` als `%40`. Ein nicht kodiertes `+` in einer Adresse wie `ada+news@example.com` wird als Leerzeichen gelesen. Mit cURL übernehmen `-G` und `--data-urlencode` die Kodierung für Sie:

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

## Filterbare Felder

Sofern kein Hinweis etwas anderes sagt, ist jeder Schlüssel in diesen Tabellen auch ein Sortierschlüssel.

### E-Mails

[E-Mails auflisten](/de/docs/api-reference/emails/list/) (`GET /emails`).

| Schlüssel | Typ | Hinweise |
| --- | --- | --- |
| `to` | String | Empfängeradresse. |
| `from` | String | Absender wie gesendet, einschließlich eines etwaigen Anzeigenamens. |
| `subject` | String | |
| `status` | Enum | `accepted`, `scheduled`, `delivered`, `loaded`, `clicked`, `attempted`, `bounced`, `failed`, `rejected`, `suppressed`, `received`, `complained`, `canceled`, `held` |
| `tag` | String | Das Tag der E-Mail. Beim Senden per API oder SMTP wird derzeit kein Tag gesetzt. |
| `spam_score` | Zahl | |
| `created_at` | Datum | Erweitert das Standardfenster von 14 Tagen nicht. Verwenden Sie `date_from` für ältere E-Mails. |
| `updated_at` | Datum | |
| `api_key_id` | String | Die `key_…`-ID des API-Schlüssels, der die E-Mail gesendet hat. |
| `sending_domain_id` | String | Die `dom_…`-ID der Versanddomain. |

Akzeptiert außerdem `search`, `type` (`outbound` oder `inbound`), `date_from` und `date_to` sowie die älteren Parameter `status`, `rcpt_to`, `mail_from`, `subject`, `api_key_id` und `sending_domain_id`.

### Domains

[Domains auflisten](/de/docs/api-reference/domains/list/) (`GET /domains`).

| Schlüssel | Typ | Hinweise |
| --- | --- | --- |
| `name` | String | |
| `created_at` | Datum | |
| `spf_status` | Enum | `ok`, `missing`, `invalid` |
| `dkim_status` | Enum | `ok`, `missing`, `invalid` |
| `return_path_status` | Enum | `ok`, `missing`, `invalid` |

Akzeptiert außerdem `search` (Domainname enthält den Wert).

### API-Schlüssel

[API-Schlüssel auflisten](/de/docs/api-reference/api-keys/list/) (`GET /api-keys`).

| Schlüssel | Typ | Hinweise |
| --- | --- | --- |
| `name` | String | |
| `scope` | String | `full` oder `sending`. |
| `type` | String | Art der Zugangsdaten. In der Weboberfläche oder per API erstellte Schlüssel haben den Typ `api`. |
| `created_at` | Datum | |

Akzeptiert außerdem `search` (Name enthält den Wert).

### Kontaktlisten und Abonnenten

[Kontaktlisten auflisten](/de/docs/api-reference/audiences/list/) (`GET /audiences`) akzeptiert `name` (String) und `created_at` (Datum) sowie `search`.

[Abonnenten auflisten](/de/docs/api-reference/audiences/subscribers/list/) (`GET /audiences/{id}/subscribers`):

| Schlüssel | Typ | Hinweise |
| --- | --- | --- |
| `email` | String | Die E-Mail-Adresse des Kontakts. |
| `first_name` | String | |
| `last_name` | String | |
| `subscribed` | Boolean | |
| `created_at` | Datum | Zeitpunkt, zu dem der Kontakt in die Kontaktliste aufgenommen wurde. |

Akzeptiert außerdem `search` (E-Mail-Adresse, Vor- oder Nachname enthält den Wert) und `subscribed=true|false`.

### Kontakte

[Kontakte auflisten](/de/docs/api-reference/contacts/list/) (`GET /contacts`) und [Kontakte exportieren](/de/docs/api-reference/contacts/export/).

| Schlüssel | Typ | Hinweise |
| --- | --- | --- |
| `email` | String | |
| `first_name` | String | |
| `last_name` | String | |
| `name` | String | Vor- und Nachname, durch ein Leerzeichen getrennt. |
| `audiences` | String | Der alphabetisch erste Name einer Kontaktliste des Kontakts. |
| `unsubscribed` | Boolean | Nur Filter. |
| `created_at` | Datum | |
| `updated_at` | Datum | |
| `audience_id` | String | Nur Filter. Nur `exact` und `not_exact`. Der Wert ist eine Kontaktlisten-ID (`aud_…`). |
| `custom_fields.<key>` | String | Nur Filter. Ersetzen Sie `<key>` durch den Schlüssel des eigenen Felds, zum Beispiel `custom_fields.company.contains=Acme`. Werte werden als Text verglichen. |

Sortieren Sie Kontakte, indem Sie `sort` auf `email`, `first_name`, `last_name`, `name`, `audiences`, `created_at` oder `updated_at` und `order` auf `asc` oder `desc` setzen. Akzeptiert außerdem `search` (Alias `q`), `audience_id` und `unsubscribed`. Die älteren Formen `filter[audience_id]`, `filter[unsubscribed]` und `filter[custom_fields][<key>]` funktionieren weiterhin.

### Kampagnen

[Kampagnen auflisten](/de/docs/api-reference/campaigns/list/) (`GET /campaigns`).

| Schlüssel | Typ | Hinweise |
| --- | --- | --- |
| `name` | String | |
| `subject` | String | |
| `status` | Enum | `draft`, `scheduled`, `queued`, `sending`, `sent`, `archived` |
| `created_at` | Datum | |
| `sent_at` | Datum | |

Akzeptiert außerdem `search` (Name oder Betreff enthält den Wert).

### Formulare

[Formulare auflisten](/de/docs/api-reference/forms/list/) (`GET /forms`).

| Schlüssel | Typ | Hinweise |
| --- | --- | --- |
| `name` | String | |
| `type` | Enum | `popup`, `full_page`, `flyout`, `embed`, `banner` |
| `status` | Enum | `draft`, `live` |
| `created_at` | Datum | |

Akzeptiert außerdem `search` (Name enthält den Wert).

### Automatisierungen

[Automatisierungen auflisten](/de/docs/api-reference/automations/list/) (`GET /automations`).

| Schlüssel | Typ | Hinweise |
| --- | --- | --- |
| `name` | String | |
| `status` | Enum | Nur Filter. `draft`, `running`, `paused`, `stopped`, `archived` |
| `context` | String | Nur Filter. `contact`, `email` oder `event`. |
| `created_at` | Datum | |

Sortieren Sie, indem Sie `sort` auf `name`, `created_at`, `updated_at` oder `last_triggered_at` und `order` auf `asc` oder `desc` setzen. Akzeptiert außerdem `filter[name]`, `filter[status]` und `filter[context]`.

[Durchläufe auflisten](/de/docs/api-reference/automations/runs/) (`GET /automations/{id}/runs`) akzeptiert `status` (String), `event` (String) und `created_at` (Datum).

### Vorlagen

[Vorlagen auflisten](/de/docs/api-reference/templates/list/) (`GET /templates`). Nur veröffentlichte Versionen werden aufgelistet.

| Schlüssel | Typ | Hinweise |
| --- | --- | --- |
| `name` | String | |
| `alias` | String | |
| `editor` | String | Nur Filter. `html`, `text`, `dragit` oder `tiptap`. |
| `subject` | String | Nur Filter. |
| `created_at` | Datum | |

Sortieren Sie, indem Sie `sort` auf `name`, `alias`, `created_at`, `updated_at` oder `published_at` und `order` auf `asc` oder `desc` setzen. Akzeptiert außerdem `filter[name]`, `filter[alias]` und `filter[editor]`.

### Sperrungen

[Sperrungen auflisten](/de/docs/api-reference/suppressions/list/) (`GET /suppressions`).

| Schlüssel | Typ | Hinweise |
| --- | --- | --- |
| `email` | String | |
| `reason` | String | |
| `type` | String | |
| `created_at` | Datum | |
| `keep_until` | Datum | Nur Filter. |

Sortieren Sie, indem Sie `sort` auf `email`, `reason`, `type` oder `created_at` und `order` auf `asc` oder `desc` setzen. Akzeptiert außerdem `search` (Alias `q`, E-Mail-Adresse oder Grund enthält den Wert).

Sperrungen akzeptieren außerdem einen JSON-Filter-Builder im Parameter `filters` (Alias `filter`). Übergeben Sie ein URL-kodiertes JSON-Objekt:

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

| Eigenschaft | Beschreibung |
| --- | --- |
| `match` | `all` (Standardwert) oder `any`. |
| `rules` | Bis zu 25 Regeln. Regeln mit unbekanntem Feld oder Operator werden ignoriert. |
| `rules[].field` | `email`, `reason`, `type` oder `created_at`. |
| `rules[].operator` | `equals`, `not_equals`, `contains`, `not_contains`, `starts_with`, `ends_with`, `greater_than`, `less_than`, `in`, `not_in`, `is_set` oder `is_not_set`. |
| `rules[].value` | Der Vergleichswert. Bei `in` und `not_in` eine kommagetrennte Liste. Für `is_set` und `is_not_set` nicht erforderlich. |

### Events

[Events auflisten](/de/docs/api-reference/events/list/) (`GET /events`).

| Schlüssel | Typ | Hinweise |
| --- | --- | --- |
| `type` | String | Der Event-Typ, etwa `email.delivered`. |
| `created_at` | Datum | Jeder Filter auf `created_at` ersetzt das Standardfenster von zwei Tagen. |

Akzeptiert außerdem `type` als kommagetrennte Liste exakter Event-Typen sowie `include_data`.

### Webhooks

[Webhooks auflisten](/de/docs/api-reference/webhooks/list/) (`GET /webhooks`).

| Schlüssel | Typ | Hinweise |
| --- | --- | --- |
| `name` | String | |
| `url` | String | |
| `enabled` | Boolean | |
| `created_at` | Datum | |

Akzeptiert außerdem `search` (Name oder URL enthält den Wert).

### E-Mail-Verifizierungslisten

[Listen auflisten](/de/docs/api-reference/email-verifications/lists/list/) (`GET /email-verification-lists`) akzeptiert `name` (String), `status` (String) und `created_at` (Datum) sowie `search` und `status`.

[Ergebnisse auflisten](/de/docs/api-reference/email-verifications/lists/results/) (`GET /email-verification-lists/{id}/results`):

| Schlüssel | Typ | Hinweise |
| --- | --- | --- |
| `email` | String | |
| `status` | String | |
| `result` | String | Zum Beispiel `safe`, `invalid` oder `disposable`. |
| `risk` | String | `low`, `medium` oder `high`. |
| `created_at` | Datum | |

Akzeptiert außerdem `status` und `result`.

### DMARC-Berichte

[Aggregierte Berichte auflisten](/de/docs/api-reference/dmarc/list/) und [Forensische Berichte auflisten](/de/docs/api-reference/dmarc/forensic/).

| Schlüssel | Typ | Hinweise |
| --- | --- | --- |
| `type` | String | `aggregate` oder `forensic`. |
| `status` | String | |
| `org_name` | String | Die Organisation, die den Bericht gesendet hat. |
| `created_at` | Datum | Zeitpunkt, zu dem Emailit den Bericht erhalten hat. |

Akzeptiert außerdem `type`, `status`, `org_name`, `from` und `to`. DMARC-Listen werden mit `limit` und `offset` paginiert. Siehe [Paginierung](/de/docs/api-reference/pagination/).

## Siehe auch

  - [Paginierung](/de/docs/api-reference/pagination/): Listenergebnisse seitenweise abrufen.
  - [Alle Endpunkte](/de/docs/api-reference/endpoints/): Alle Endpunkte und der jeweils benötigte Scope.

---
Quelle: https://emailit.com/de/docs/api-reference/filtering/