# Filtragem e ordenação

> Filtre e ordene os endpoints de listagem da API com parâmetros de consulta key.condition=value, match e order. Todas as condições e os campos filtráveis de cada recurso.

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:

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

| Parâmetro | Descrição |
| --- | --- |
| `<key>.<condition>=<value>` | Um filtro. Adicione quantos precisar, inclusive vários na mesma chave. |
| `match` | Como os filtros se combinam. `all` (padrão) retorna as linhas que correspondem a todos os filtros. `or` retorna as linhas que correspondem a pelo menos um. |
| `order` | A chave de ordenação. Deve ser uma das chaves de ordenação do endpoint. |
| `direction` | `asc` ou `desc`. Se você passar `order` sem `direction`, os resultados são ordenados de forma crescente. |

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](/pt/docs/api-reference/contacts/list/), [Listar templates](/pt/docs/api-reference/templates/list/), [Listar automações](/pt/docs/api-reference/automations/list/) e [Listar supressões](/pt/docs/api-reference/suppressions/list/), `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.

| Condição | String | Number | Date | Boolean | Enum | Corresponde quando o campo… |
| --- | --- | --- | --- | --- | --- | --- |
| `exact` | Sim | Sim | Sim | Sim | Sim | é igual ao valor. Strings são comparadas diferenciando maiúsculas de minúsculas. Datas são comparadas pelo dia do calendário. |
| `not_exact` | Sim | Sim |  | Sim | Sim | é diferente do valor. |
| `contains` | Sim |  |  |  |  | contém o valor, sem diferenciar maiúsculas de minúsculas. |
| `not_contains` | Sim |  |  |  |  | não contém o valor, sem diferenciar maiúsculas de minúsculas. Campos vazios correspondem. |
| `starts_with` | Sim |  |  |  |  | começa com o valor, sem diferenciar maiúsculas de minúsculas. |
| `ends_with` | Sim |  |  |  |  | termina com o valor, sem diferenciar maiúsculas de minúsculas. |
| `gt`, `gte` | | Sim |  |  |  | é maior que (ou igual a) o valor. |
| `lt`, `lte` | | Sim |  |  |  | é menor que (ou igual a) o valor. |
| `before` |  |  | Sim |  |  | é anterior ao valor. |
| `after` |  |  | Sim |  |  | é posterior ao valor. |
| `empty` | Sim | Sim | Sim |  |  | não tem valor. Para strings, uma string vazia conta como vazia. |
| `not_empty` | Sim | Sim | Sim |  |  | tem um valor. |

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:

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

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

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

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

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

| Chave | Tipo | Observações |
| --- | --- | --- |
| `to` | string | Endereço do destinatário. |
| `from` | string | Remetente como foi enviado, incluindo o nome de exibição, se houver. |
| `subject` | string | |
| `status` | enum | `accepted`, `scheduled`, `delivered`, `loaded`, `clicked`, `attempted`, `bounced`, `failed`, `rejected`, `suppressed`, `received`, `complained`, `canceled`, `held` |
| `tag` | string | A tag do e-mail. No momento, enviar pela API ou por SMTP não define uma tag. |
| `spam_score` | number | |
| `created_at` | date | Não amplia a janela padrão de 14 dias. Use `date_from` para e-mails mais antigos. |
| `updated_at` | date | |
| `api_key_id` | string | O ID `key_…` da chave de API que enviou o e-mail. |
| `sending_domain_id` | string | O ID `dom_…` do domínio de envio. |

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

| Chave | Tipo | Observações |
| --- | --- | --- |
| `name` | string | |
| `created_at` | date | |
| `spf_status` | enum | `ok`, `missing`, `invalid` |
| `dkim_status` | enum | `ok`, `missing`, `invalid` |
| `return_path_status` | enum | `ok`, `missing`, `invalid` |

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

### Chaves de API

[Listar chaves de API](/pt/docs/api-reference/api-keys/list/) (`GET /api-keys`).

| Chave | Tipo | Observações |
| --- | --- | --- |
| `name` | string | |
| `scope` | string | `full` ou `sending`. |
| `type` | string | Tipo de credencial. As chaves criadas no painel ou pela API são `api`. |
| `created_at` | date | |

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

### Listas de contatos e inscritos

[Listar listas de contatos](/pt/docs/api-reference/audiences/list/) (`GET /audiences`) aceita `name` (string) e `created_at` (date), além de `search`.

[Listar inscritos](/pt/docs/api-reference/audiences/subscribers/list/) (`GET /audiences/{id}/subscribers`):

| Chave | Tipo | Observações |
| --- | --- | --- |
| `email` | string | O endereço de e-mail do contato. |
| `first_name` | string | |
| `last_name` | string | |
| `subscribed` | boolean | |
| `created_at` | date | Quando o contato entrou na lista. |

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

### Contatos

[Listar contatos](/pt/docs/api-reference/contacts/list/) (`GET /contacts`) e [Exportar contatos](/pt/docs/api-reference/contacts/export/).

| Chave | Tipo | Observações |
| --- | --- | --- |
| `email` | string | |
| `first_name` | string | |
| `last_name` | string | |
| `name` | string | Nome e sobrenome unidos por um espaço. |
| `audiences` | string | O primeiro nome, em ordem alfabética, das listas de contatos do contato. |
| `unsubscribed` | boolean | Apenas filtro. |
| `created_at` | date | |
| `updated_at` | date | |
| `audience_id` | string | Apenas filtro. Apenas `exact` e `not_exact`. O valor é um ID de lista de contatos (`aud_…`). |
| `custom_fields.<key>` | string | Apenas filtro. Substitua `<key>` pela chave do campo personalizado, por exemplo `custom_fields.company.contains=Acme`. Os valores são comparados como texto. |

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

| Chave | Tipo | Observações |
| --- | --- | --- |
| `name` | string | |
| `subject` | string | |
| `status` | enum | `draft`, `scheduled`, `queued`, `sending`, `sent`, `archived` |
| `created_at` | date | |
| `sent_at` | date | |

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

### Formulários

[Listar formulários](/pt/docs/api-reference/forms/list/) (`GET /forms`).

| Chave | Tipo | Observações |
| --- | --- | --- |
| `name` | string | |
| `type` | enum | `popup`, `full_page`, `flyout`, `embed`, `banner` |
| `status` | enum | `draft`, `live` |
| `created_at` | date | |

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

### Automações

[Listar automações](/pt/docs/api-reference/automations/list/) (`GET /automations`).

| Chave | Tipo | Observações |
| --- | --- | --- |
| `name` | string | |
| `status` | enum | Apenas filtro. `draft`, `running`, `paused`, `stopped`, `archived` |
| `context` | string | Apenas filtro. `contact`, `email` ou `event`. |
| `created_at` | date | |

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](/pt/docs/api-reference/automations/runs/) (`GET /automations/{id}/runs`) aceita `status` (string), `event` (string) e `created_at` (date).

### Templates

[Listar templates](/pt/docs/api-reference/templates/list/) (`GET /templates`). Apenas as versões publicadas são listadas.

| Chave | Tipo | Observações |
| --- | --- | --- |
| `name` | string | |
| `alias` | string | |
| `editor` | string | Apenas filtro. `html`, `text`, `dragit` ou `tiptap`. |
| `subject` | string | Apenas filtro. |
| `created_at` | date | |

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

| Chave | Tipo | Observações |
| --- | --- | --- |
| `email` | string | |
| `reason` | string | |
| `type` | string | |
| `created_at` | date | |
| `keep_until` | date | Apenas filtro. |

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:

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

| Propriedade | Descrição |
| --- | --- |
| `match` | `all` (padrão) ou `any`. |
| `rules` | Até 25 regras. Regras com um campo ou operador desconhecido são ignoradas. |
| `rules[].field` | `email`, `reason`, `type` ou `created_at`. |
| `rules[].operator` | `equals`, `not_equals`, `contains`, `not_contains`, `starts_with`, `ends_with`, `greater_than`, `less_than`, `in`, `not_in`, `is_set` ou `is_not_set`. |
| `rules[].value` | O valor a comparar. Para `in` e `not_in`, uma lista separada por vírgulas. Não é necessário para `is_set` e `is_not_set`. |

### Eventos

[Listar eventos](/pt/docs/api-reference/events/list/) (`GET /events`).

| Chave | Tipo | Observações |
| --- | --- | --- |
| `type` | string | O tipo de evento, como `email.delivered`. |
| `created_at` | date | Qualquer filtro `created_at` substitui a janela padrão de dois dias. |

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

### Webhooks

[Listar webhooks](/pt/docs/api-reference/webhooks/list/) (`GET /webhooks`).

| Chave | Tipo | Observações |
| --- | --- | --- |
| `name` | string | |
| `url` | string | |
| `enabled` | boolean | |
| `created_at` | date | |

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

### Listas de verificação de e-mails

[Listar listas](/pt/docs/api-reference/email-verifications/lists/list/) (`GET /email-verification-lists`) aceita `name` (string), `status` (string) e `created_at` (date), além de `search` e `status`.

[Listar resultados](/pt/docs/api-reference/email-verifications/lists/results/) (`GET /email-verification-lists/{id}/results`):

| Chave | Tipo | Observações |
| --- | --- | --- |
| `email` | string | |
| `status` | string | |
| `result` | string | Por exemplo, `safe`, `invalid` ou `disposable`. |
| `risk` | string | `low`, `medium` ou `high`. |
| `created_at` | date | |

Também aceita `status` e `result`.

### Relatórios DMARC

[Listar relatórios agregados](/pt/docs/api-reference/dmarc/list/) e [Listar relatórios forenses](/pt/docs/api-reference/dmarc/forensic/).

| Chave | Tipo | Observações |
| --- | --- | --- |
| `type` | string | `aggregate` ou `forensic`. |
| `status` | string | |
| `org_name` | string | A organização que enviou o relatório. |
| `created_at` | date | Quando o Emailit recebeu o relatório. |

Também aceita `type`, `status`, `org_name`, `from` e `to`. As listas DMARC são paginadas com `limit` e `offset`. Consulte [Paginação](/pt/docs/api-reference/pagination/).

## Veja também

  - [Paginação](/pt/docs/api-reference/pagination/): Percorra os resultados das listagens página por página.
  - [Todos os endpoints](/pt/docs/api-reference/endpoints/): Todos os endpoints e o escopo que cada um exige.

---
Fonte: https://emailit.com/pt/docs/api-reference/filtering/