Filtern und Sortieren

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:

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

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, Vorlagen auflisten, Automatisierungen auflisten und Sperrungen auflisten 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.

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:

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

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

Domains mit fehlerhaftem DKIM-Eintrag, älteste zuerst:

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

Filterbare Felder

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

E-Mails

E-Mails auflisten (GET /emails).

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

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

API-Schlüssel

API-Schlüssel auflisten (GET /api-keys).

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

Kontaktlisten und Abonnenten

Kontaktlisten auflisten (GET /audiences) akzeptiert name (String) und created_at (Datum) sowie search.

Abonnenten auflisten (GET /audiences/{id}/subscribers):

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

Kontakte

Kontakte auflisten (GET /contacts) und Kontakte exportieren.

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

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

Formulare

Formulare auflisten (GET /forms).

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

Automatisierungen

Automatisierungen auflisten (GET /automations).

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 (GET /automations/{id}/runs) akzeptiert status (String), event (String) und created_at (Datum).

Vorlagen

Vorlagen auflisten (GET /templates). Nur veröffentlichte Versionen werden aufgelistet.

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

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:

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

Events

Events auflisten (GET /events).

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

Webhooks

Webhooks auflisten (GET /webhooks).

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

E-Mail-Verifizierungslisten

Listen auflisten (GET /email-verification-lists) akzeptiert name (String), status (String) und created_at (Datum) sowie search und status.

Ergebnisse auflisten (GET /email-verification-lists/{id}/results):

Akzeptiert außerdem status und result.

DMARC-Berichte

Aggregierte Berichte auflisten und Forensische Berichte auflisten.

Akzeptiert außerdem type, status, org_name, from und to. DMARC-Listen werden mit limit und offset paginiert. Siehe Paginierung.

Siehe auch