Filtragem e ordenação

Os endpoints de listagem aceitam a mesma linguagem de filtros de um único nível na query string: um parâmetro de consulta por filtro, combinados com match e ordenados com order e direction. Esta página explica a sintaxe, as condições de cada tipo de campo e todos os campos pelos quais você pode filtrar e ordenar, recurso por recurso.

Sintaxe

Um filtro é um parâmetro de consulta chamado <key>.<condition> com o valor a comparar:

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

Sem order, as listas retornam primeiro os objetos mais recentes.

Os filtros são combinados com AND com quaisquer parâmetros dedicados do endpoint, como search ou type. match controla apenas como os filtros key.condition se combinam entre si.

Chaves desconhecidas, condições que não se aplicam ao tipo da chave e valores que não podem ser interpretados (uma data inválida, algo que não é um número, um valor de enum que não existe ou um valor vazio) são ignorados em vez de rejeitados. Se um filtro parecer não ter efeito, confira a grafia dele.

Parâmetros de ordenação legados

Alguns endpoints também aceitam sort=<key> com order=asc ou order=desc. Em Listar contatos, Listar templates, Listar automações e Listar supressões, order aceita apenas asc ou desc, então ordene essas listas com sort=<key>&order=<direction> em vez de order=<key>. A forma legada funciona em todos os endpoints de listagem.

Condições

Cada chave tem um tipo, e cada tipo aceita as próprias condições.

Formatos de valor:

• Datas. Qualquer data ou data e hora ISO 8601, como 2026-09-01 ou 2026-09-01T14:30:00Z. before e after são exclusivos.
• Booleanos. true ou 1 significam verdadeiro. Qualquer outro valor significa falso.
• Enums. Um dos valores listados para a chave abaixo.
• empty e not_empty. O valor é ignorado, mas o parâmetro precisa de um. Use 1, por exemplo spam_score.empty=1.

Exemplos

E-mails com bounce ou com falha desde 1º de setembro:

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

Como match=or se aplica a todos os filtros da requisição, não é possível misturar AND e OR. Para combinar um intervalo de datas com status alternativos em Listar e-mails, use o parâmetro dedicado date_from para a data, como no exemplo, já que os parâmetros dedicados sempre se aplicam com AND.

Contatos da Acme cujo campo personalizado plan é pro, ordenados por e-mail:

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

Domínios com um registro DKIM com falha, do mais antigo para o mais recente:

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

Codificação de URL

Codifique os caracteres reservados nos valores: + como %2B, & como %26, # como %23, um espaço como %20 e @ como %40. Um + não codificado em um endereço como ada+news@example.com é lido como espaço. Com o cURL, -G e --data-urlencode fazem a codificação por você:

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

Campos filtráveis

Salvo indicação em contrário nas observações, todas as chaves destas tabelas também são chaves de ordenação.

E-mails

Listar e-mails (GET /emails).

Também aceita search, type (outbound ou inbound), date_from e date_to, além dos parâmetros mais antigos status, rcpt_to, mail_from, subject, api_key_id e sending_domain_id.

Domínios

Listar domínios (GET /domains).

Também aceita search (o nome do domínio contém).

Chaves de API

Listar chaves de API (GET /api-keys).

Também aceita search (o nome contém).

Listas de contatos e inscritos

Listar listas de contatos (GET /audiences) aceita name (string) e created_at (date), além de search.

Listar inscritos (GET /audiences/{id}/subscribers):

Também aceita search (o e-mail, o nome ou o sobrenome contém) e subscribed=true|false.

Contatos

Listar contatos (GET /contacts) e Exportar contatos.

Ordene os contatos com sort definido como email, first_name, last_name, name, audiences, created_at ou updated_at, e order definido como asc ou desc. Também aceita search (alias q), audience_id e unsubscribed. As formas mais antigas filter[audience_id], filter[unsubscribed] e filter[custom_fields][<key>] continuam funcionando.

Campanhas

Listar campanhas (GET /campaigns).

Também aceita search (o nome ou o assunto contém).

Formulários

Listar formulários (GET /forms).

Também aceita search (o nome contém).

Automações

Listar automações (GET /automations).

Ordene com sort definido como name, created_at, updated_at ou last_triggered_at, e order definido como asc ou desc. Também aceita filter[name], filter[status] e filter[context].

Listar execuções (GET /automations/{id}/runs) aceita status (string), event (string) e created_at (date).

Templates

Listar templates (GET /templates). Apenas as versões publicadas são listadas.

Ordene com sort definido como name, alias, created_at, updated_at ou published_at, e order definido como asc ou desc. Também aceita filter[name], filter[alias] e filter[editor].

Supressões

Listar supressões (GET /suppressions).

Ordene com sort definido como email, reason, type ou created_at, e order definido como asc ou desc. Também aceita search (alias q; o e-mail ou o motivo contém).

As supressões também aceitam um construtor de filtros JSON no parâmetro filters (alias filter). Passe um objeto JSON codificado para URL:

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

Eventos

Listar eventos (GET /events).

Também aceita type como uma lista de tipos de evento exatos separados por vírgulas, e include_data.

Webhooks

Listar webhooks (GET /webhooks).

Também aceita search (o nome ou a URL contém).

Listas de verificação de e-mails

Listar listas (GET /email-verification-lists) aceita name (string), status (string) e created_at (date), além de search e status.

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

Também aceita status e result.

Relatórios DMARC

Listar relatórios agregados e Listar relatórios forenses.

Também aceita type, status, org_name, from e to. As listas DMARC são paginadas com limit e offset. Consulte Paginação.

Veja também