Filtering and sorting

List endpoints accept the same flat filter language in the query string: one query parameter per filter, combined with match, and sorted with order and direction. This page covers the syntax, the conditions for each field type, and every field you can filter and sort on, resource by resource.

Syntax

A filter is a query parameter named <key>.<condition> with the value to compare against:

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

Without order, lists return the newest objects first.

Filters are combined with any dedicated parameters of the endpoint, such as search or type, using AND. match only controls how the key.condition filters combine with each other.

Unknown keys, conditions that don’t fit the key’s type, and values that can’t be parsed (an invalid date, a non-number, an enum value that doesn’t exist, or an empty value) are ignored rather than rejected. If a filter seems to have no effect, check its spelling.

Legacy sort parameters

Some endpoints also accept sort=<key> with order=asc or order=desc. On List contacts, List templates, List automations and List suppressions, order only accepts asc or desc, so sort those lists with sort=<key>&order=<direction> instead of order=<key>. The legacy form works on every list endpoint.

Conditions

Each key has a type, and each type accepts its own conditions.

Value formats:

• Dates. Any ISO 8601 date or date-time, such as 2026-09-01 or 2026-09-01T14:30:00Z. before and after are exclusive.
• Booleans. true or 1 mean true. Any other value means false.
• Enums. One of the values listed for the key below.
• empty and not_empty. The value is ignored, but the parameter needs one. Use 1, for example spam_score.empty=1.

Examples

Bounced or failed emails since September 1:

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

Because match=or applies to every filter in the request, you can’t mix AND and OR. To combine a date range with alternative statuses on List emails, use the dedicated date_from parameter for the date as shown, since dedicated parameters always apply with AND.

Contacts at Acme whose plan custom field is pro, sorted by email:

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

Domains with a failing DKIM record, oldest first:

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

URL encoding

Encode reserved characters in values: + as %2B, & as %26, # as %23, a space as %20 and @ as %40. An unencoded + in an address like ada+news@example.com is read as a space. With cURL, -G and --data-urlencode handle the encoding for you:

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

Filterable fields

Unless a note says otherwise, every key in these tables is also a sort key.

Emails

List emails (GET /emails).

Also accepts search, type (outbound or inbound), date_from and date_to, plus the older status, rcpt_to, mail_from, subject, api_key_id and sending_domain_id parameters.

Domains

List domains (GET /domains).

Also accepts search (domain name contains).

API keys

List API keys (GET /api-keys).

Also accepts search (name contains).

Audiences and subscribers

List audiences (GET /audiences) accepts name (string) and created_at (date), plus search.

List subscribers (GET /audiences/{id}/subscribers):

Also accepts search (email, first or last name contains) and subscribed=true|false.

Contacts

List contacts (GET /contacts) and Export contacts.

Sort contacts with sort set to email, first_name, last_name, name, audiences, created_at or updated_at, and order set to asc or desc. Also accepts search (alias q), audience_id and unsubscribed. The older filter[audience_id], filter[unsubscribed] and filter[custom_fields][<key>] forms still work.

Campaigns

List campaigns (GET /campaigns).

Also accepts search (name or subject contains).

Forms

List forms (GET /forms).

Also accepts search (name contains).

Automations

List automations (GET /automations).

Sort with sort set to name, created_at, updated_at or last_triggered_at, and order set to asc or desc. Also accepts filter[name], filter[status] and filter[context].

List runs (GET /automations/{id}/runs) accepts status (string), event (string) and created_at (date).

Templates

List templates (GET /templates). Only published versions are listed.

Sort with sort set to name, alias, created_at, updated_at or published_at, and order set to asc or desc. Also accepts filter[name], filter[alias] and filter[editor].

Suppressions

List suppressions (GET /suppressions).

Sort with sort set to email, reason, type or created_at, and order set to asc or desc. Also accepts search (alias q, email or reason contains).

Suppressions also accept a JSON filter builder in the filters parameter (alias filter). Pass a URL-encoded JSON object:

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

Events

List events (GET /events).

Also accepts type as a comma-separated list of exact event types, and include_data.

Webhooks

List webhooks (GET /webhooks).

Also accepts search (name or URL contains).

Email verification lists

List lists (GET /email-verification-lists) accepts name (string), status (string) and created_at (date), plus search and status.

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

Also accepts status and result.

DMARC reports

List aggregate reports and List forensic reports.

Also accepts type, status, org_name, from and to. DMARC lists page with limit and offset. See Pagination.

Related