Pular para o conteúdo
Docs

Salve filtros sobre os seus contatos, liste quem corresponde a eles e acompanhe os segmentos rastreados ao longo do tempo.

URL basehttps://api.emailit.com/v2AutenticaçãoErrosLimites de requisições

Criar um segmento

Cria um segmento: um filtro salvo sobre os contatos do workspace. Requer uma chave de API com escopo full.

Um segmento contém os contatos da sua origem (os inscritos de audience_ids, ou todos os contatos quando ele estiver vazio) que correspondem às suas conditions. A participação é avaliada em tempo real sempre que o segmento é contado, listado, pré-visualizado ou usado por uma campanha que está sendo enviada. Consulte Segmentos.

Cada plano inclui um número de segmentos por workspace, rastreados ou não. Consulte Limites.

POST/segments

Parâmetros do corpo

namestringobrigatório
Nome do segmento, com até 191 caracteres.
descriptionstring | null
Observação para a sua equipe, com até 1.000 caracteres.
audience_idsstring[]
A origem: IDs de listas de contatos (aud_…) deste workspace, até 100. O segmento só contém contatos inscritos em pelo menos uma delas. Vazio ou omitido significa todos os contatos do workspace.
conditionsobject
As regras às quais os contatos devem corresponder, descritas em Condições. Omita-o para incluir todos da origem.
trackedbooleanpadrão: false
Armazena os membros do segmento para que as entradas e saídas de contatos se tornem eventos para automações e webhooks. Incluído nos planos Pro, Business e Custom. Você o escolhe aqui e não pode mudá-lo depois. Consulte Segmentos rastreados.

Condições

conditions contém grupos de regras. O match de nível superior combina os grupos, e o match de cada grupo combina as regras dele:

JSON
{
  "match": "all",
  "groups": [
    { "match": "any", "rules": [{ "field": "email_domain", "operator": "in", "value": ["acme.com", "globex.io"] }] },
    { "match": "all", "rules": [{ "field": "status", "operator": "equals", "value": "subscribed" }] }
  ]
}
  • match é all (padrão) ou any, no nível superior e em cada grupo.
  • Omita conditions, ou não envie grupos, para incluir todos da origem. Os grupos vazios são descartados.
  • O formato plano { "match": "any", "rules": [...] } também é aceito e armazenado como um único grupo.
  • Um segmento pode ter até 10 grupos e 50 regras no total.

Campos

Campo Tipo Observações
email string
email_domain string A parte do endereço depois de @.
first_name, last_name string
status enum subscribed (não descadastrado globalmente e inscrito em pelo menos uma lista, para que as campanhas possam alcançar o contato) ou unsubscribed. Operadores: equals, not_equals.
created_at, updated_at datetime Quando o contato foi criado ou alterado pela última vez, comparado em UTC.
audience audience Participação como inscrito. in corresponde aos contatos inscritos em qualquer um dos IDs de lista, e not_in, aos contatos que não estão inscritos em nenhum deles.
tags tags As tags do contato. Os valores são comparados em minúsculas.
score score A pontuação de lead do contato.
custom_fields.<key> depende do campo Os campos de texto são string, os de número number, os de data date (YYYY-MM-DD), os booleanos boolean, os de seleção enum e os de seleção múltipla multi.
orders_count, total_spent, average_order_value metric Calculados a partir dos pedidos do contato. 0 para contatos sem pedidos. Os valores estão na moeda dos pedidos do contato.
first_order_at, last_order_at moment Sem valor para contatos sem pedidos.
expected_next_order_at moment O último pedido mais o intervalo médio do contato entre pedidos. Tem valor a partir do segundo pedido e pode estar no futuro.
churn_risk enum low, medium ou high: o tempo desde o último pedido comparado com o intervalo habitual do contato (no mínimo 14 dias), ou com 90 dias para quem comprou uma única vez. Sem valor se não houver pedidos.
last_active_at moment A última vez que o script de rastreamento viu o contato no seu site.
purchased purchase Pedidos; consulte Regras de atividade.
viewed_product view Visualizações de produtos registradas pelo script de rastreamento.
cart cart Carrinhos abertos e abandonados.
used_coupon coupon Pedidos que usaram um código de cupom.
campaign_activity campaign_activity E-mails de campanha recebidos, abertos ou clicados.

Listar os campos de segmentos retorna os campos do seu workspace, incluindo os campos personalizados e as listas de contatos dele, com os operadores que cada um aceita.

Operadores

Tipo Operadores
string equals, not_equals, contains, not_contains, starts_with, ends_with, in, not_in, is_set, is_not_set
number equals, not_equals, greater_than, greater_than_or_equal, less_than, less_than_or_equal, between, is_set, is_not_set
date on, before, after, between, in_last_days, more_than_days_ago, in_next_days, is_set, is_not_set
datetime on, before, after, between, in_last_days, more_than_days_ago
boolean is_true, is_false, is_set, is_not_set
enum in, not_in, is_set, is_not_set
multi in (tem qualquer um de), contains_all (tem todos de), not_in (não tem nenhum de), is_set, is_not_set
audience in, not_in
tags in (tem qualquer uma de), contains_all (tem todas de), not_in (não tem nenhuma de), is_set (tem alguma tag), is_not_set (não tem tags)
score equals, not_equals, greater_than, greater_than_or_equal, less_than, less_than_or_equal, between
metric equals, not_equals, greater_than, greater_than_or_equal, less_than, less_than_or_equal, between
moment on, before, after, between, in_last_days, more_than_days_ago, in_next_days, is_set, is_not_set
purchase, view, coupon has, has_not
cart has_open_cart, has_abandoned_cart, has_no_open_cart
campaign_activity received, not_received, opened, not_opened, clicked, not_clicked, received_not_opened, received_not_clicked

Valores

  • As comparações de texto em campos string não diferenciam maiúsculas de minúsculas. Os valores de seleção e de seleção múltipla devem corresponder exatamente.
  • not_equals, not_contains e not_in também correspondem a contatos que não têm valor.
  • in, not_in e contains_all recebem uma lista de até 100 valores. Os valores de texto podem ter até 500 caracteres.
  • between recebe [from, to], com os dois extremos incluídos: dois números ou duas datas YYYY-MM-DD.
  • on, before e after recebem uma data YYYY-MM-DD. before e after não incluem esse dia.
  • in_last_days, more_than_days_ago e in_next_days recebem um número inteiro de dias de 1 a 3650, contado a partir do momento em que o segmento é avaliado. Os campos personalizados de data comparam dias do calendário em UTC; created_at e updated_at usam horários exatos, então in_last_days com 7 significa as últimas 7 × 24 horas.
  • is_set, is_not_set, is_true e is_false não recebem valor. is_true corresponde a true, 1, yes e on; is_false corresponde a false, 0, no e off.
  • Uma regra salva que não se aplica mais, por exemplo depois que o campo personalizado dela mudou de tipo, não corresponde a nenhum contato. As regras sobre um campo personalizado excluído continuam funcionando com os valores que os contatos ainda têm, mas as novas regras devem usar um campo existente.

Regras de atividade

purchased, viewed_product, cart, used_coupon e campaign_activity recebem um objeto como value. Todas as chaves são opcionais.

Campo Chaves do valor
purchased days: só os pedidos feitos nos últimos N dias. product_ids: pedidos com qualquer um destes produtos (os IDs de produto da sua loja). categories: pedidos com um produto em qualquer uma destas categorias. min_count: pelo menos este número de pedidos correspondentes (padrão 1, até 1.000). Os pedidos cancelados não contam.
viewed_product days, product_ids, categories e min_count, como acima, contando as visualizações de produtos.
cart days, só com has_abandoned_cart: carrinhos abandonados nos últimos N dias. has_open_cart corresponde a um carrinho ativo, e has_no_open_cart, aos contatos sem carrinho ativo ou abandonado.
used_coupon days e coupon: a chave de um cupom. Sem coupon, qualquer código conta.
campaign_activity campaign_id: uma campanha (cmp_...), ou qualquer campanha quando ausente. days: só os últimos N dias, ou todo o período quando ausente.

days é um número inteiro de 1 a 3650. has_not é o oposto de has com o mesmo valor.

JSON
{
  "match": "all",
  "groups": [
    { "match": "all", "rules": [
      { "field": "purchased", "operator": "has", "value": { "categories": ["Shoes"], "days": 180 } },
      { "field": "churn_risk", "operator": "in", "value": ["medium", "high"] },
      { "field": "campaign_activity", "operator": "clicked", "value": { "days": 90 } }
    ] }
  ]
}

received_not_opened e received_not_clicked correspondem aos contatos que receberam pelo menos um e-mail de campanha correspondente e não abriram nenhum deles (ou não clicaram em nenhum deles, respectivamente). As aberturas são aproximadas: o Apple Mail carrega as imagens de todos os e-mails que recebe.

Retorno

Retorna 201 Created com o objeto de segmento, incluindo contacts_count e subscribed_count. Um novo segmento rastreado começa com tracking.status definido como syncing enquanto o Emailit registra os membros atuais dele.

Status Quando
400 name está ausente, ou um campo tem o tipo errado.
403 tracked é true e o plano não inclui segmentos rastreados. O corpo é {"error": "plan_required", "required_plan": "pro", ...}.
422 Um campo ou uma regra é inválido: errors é indexado pelo caminho dele, como conditions.groups.0.rules.1.value, e message repete o primeiro problema. Também é retornado quando o workspace atingiu o limite de segmentos do plano; esse corpo inclui usage.used e usage.limit.
POST/segments
Terminal
curl -X POST https://api.emailit.com/v2/segments \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Pro customers renewing soon",
    "audience_ids": ["aud_2nYs8Qm4Hc1Zx7Vb3Ne6Tg9Lk2a"],
    "conditions": {
      "match": "all",
      "groups": [{
        "match": "all",
        "rules": [
          { "field": "custom_fields.plan", "operator": "in", "value": ["pro", "enterprise"] },
          { "field": "custom_fields.renews_on", "operator": "in_next_days", "value": 30 }
        ]
      }]
    },
    "tracked": true
  }'
JSON
{
  "object": "segment",
  "id": "seg_2nYs9Kd1Lq3vB8wXcE4fT7uRm0p",
  "name": "Pro customers renewing soon",
  "description": null,
  "audience_ids": ["aud_2nYs8Qm4Hc1Zx7Vb3Ne6Tg9Lk2a"],
  "conditions": {
    "match": "all",
    "groups": [
      {
        "match": "all",
        "rules": [
          { "field": "custom_fields.plan", "operator": "in", "value": ["pro", "enterprise"] },
          { "field": "custom_fields.renews_on", "operator": "in_next_days", "value": 30 }
        ]
      }
    ]
  },
  "tracked": true,
  "tracking": {
    "status": "syncing",
    "synced_at": null
  },
  "contacts_count": 412,
  "subscribed_count": 398,
  "created_at": "2026-10-18T12:00:00.000000+00:00",
  "updated_at": "2026-10-18T12:00:00.000000+00:00"
}

Obter um segmento

Obtém um segmento e conta os contatos dele no momento da chamada. Requer uma chave de API com escopo full.

GET/segments/{id}

Parâmetros de caminho

idstringobrigatório
O ID do segmento (seg_…).

Retorno

Retorna o objeto de segmento.

objectstring
Sempre segment.
idstring
ID do segmento, com o prefixo seg_.
namestring
Nome do segmento.
descriptionstring | null
Observação para a sua equipe.
audience_idsstring[]
As listas de contatos de origem. Vazio significa todos os contatos do workspace.
conditionsobject
As regras, no formato { "match", "groups": [{ "match", "rules": [...] }] }. Consulte Criar um segmento.
trackedboolean
Se o segmento armazena os seus membros e informa as entradas e saídas. Consulte Segmentos rastreados.
trackingobject | null

null para segmentos que não são rastreados. Para segmentos rastreados:

  • status: active quando os membros são mantidos atualizados, syncing enquanto o Emailit registra os membros atuais depois que o segmento foi criado ou que o rastreamento foi retomado, ou paused quando o plano do workspace não inclui mais segmentos rastreados.
  • synced_at: quando o segmento inteiro foi comparado com as regras dele pela última vez, ou null antes da primeira comparação.
contacts_countinteger
Contatos que correspondem ao segmento agora.
subscribed_countinteger
A parte de contacts_count para a qual as campanhas podem enviar: contatos que não estão descadastrados globalmente e estão inscritos em pelo menos uma lista. Os endereços suprimidos continuam sendo contados.
created_at, updated_atstring
Timestamps em UTC.

Retorna 404 se o segmento não existir.

GET/segments/{id}
Terminal
curl https://api.emailit.com/v2/segments/seg_2nYs9Kd1Lq3vB8wXcE4fT7uRm0p \
  -H "Authorization: Bearer $EMAILIT_API_KEY"
JSON
{
  "object": "segment",
  "id": "seg_2nYs9Kd1Lq3vB8wXcE4fT7uRm0p",
  "name": "Pro customers renewing soon",
  "description": "Pro and Enterprise plans that renew in the next 30 days.",
  "audience_ids": ["aud_2nYs8Qm4Hc1Zx7Vb3Ne6Tg9Lk2a"],
  "conditions": {
    "match": "all",
    "groups": [
      {
        "match": "all",
        "rules": [
          { "field": "custom_fields.plan", "operator": "in", "value": ["pro", "enterprise"] },
          { "field": "custom_fields.renews_on", "operator": "in_next_days", "value": 30 }
        ]
      }
    ]
  },
  "tracked": true,
  "tracking": {
    "status": "active",
    "synced_at": "2026-10-18T00:30:04.211000+00:00"
  },
  "contacts_count": 412,
  "subscribed_count": 398,
  "created_at": "2026-10-02T09:14:03.551000+00:00",
  "updated_at": "2026-10-02T09:14:03.551000+00:00"
}

Atualizar um segmento

Atualiza os campos que você passar e deixa os outros como estão. audience_ids e conditions são substituídos por inteiro. Requer uma chave de API com escopo full.

As campanhas avaliam um segmento no momento do envio, então as novas regras valem para todas as campanhas que ainda não foram enviadas, incluindo as agendadas.

Em um segmento rastreado, alterar audience_ids ou conditions compara os membros armazenados com as novas regras. Os contatos que entram ou saem por causa da alteração enviam os eventos segment.contact_added e segment.contact_removed com reason definido como segment_updated. Os webhooks os recebem, mas eles não iniciam automações.

POST/segments/{id}

Parâmetros de caminho

idstringobrigatório
O ID do segmento (seg_…).

Parâmetros do corpo

namestring
Novo nome, com até 191 caracteres. Não pode ficar vazio.
descriptionstring | null
Observação para a sua equipe, com até 1.000 caracteres. null ou uma string vazia a apaga.
audience_idsstring[]
IDs das listas de contatos de origem. [] significa todos os contatos do workspace.
conditionsobject
As regras. Consulte Criar um segmento.
trackedboolean
Aceito apenas com o valor atual do segmento. O rastreamento é escolhido quando um segmento é criado; para mudá-lo, crie um novo segmento.

Retorno

Retorna o objeto de segmento atualizado, com contagens recalculadas.

Status Quando
404 O segmento não existe.
422 Um campo ou uma regra é inválido, ou tracked é diferente do valor atual do segmento. errors é indexado pelo caminho do campo.
POST/segments/{id}
Terminal
curl -X POST https://api.emailit.com/v2/segments/seg_2nYs9Kd1Lq3vB8wXcE4fT7uRm0p \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Pro customers renewing this month" }'
JSON
{
  "object": "segment",
  "id": "seg_2nYs9Kd1Lq3vB8wXcE4fT7uRm0p",
  "name": "Pro customers renewing this month",
  "description": "Pro and Enterprise plans that renew in the next 30 days.",
  "audience_ids": ["aud_2nYs8Qm4Hc1Zx7Vb3Ne6Tg9Lk2a"],
  "conditions": {
    "match": "all",
    "groups": [
      {
        "match": "all",
        "rules": [
          { "field": "custom_fields.plan", "operator": "in", "value": ["pro", "enterprise"] },
          { "field": "custom_fields.renews_on", "operator": "in_next_days", "value": 30 }
        ]
      }
    ]
  },
  "tracked": true,
  "tracking": {
    "status": "active",
    "synced_at": "2026-10-18T00:30:04.211000+00:00"
  },
  "contacts_count": 412,
  "subscribed_count": 398,
  "created_at": "2026-10-02T09:14:03.551000+00:00",
  "updated_at": "2026-10-18T12:00:00.000000+00:00"
}

Listar segmentos

Retorna os segmentos do workspace, dos mais recentes para os mais antigos, com quantos dos segmentos do plano estão em uso. Requer uma chave de API com escopo full.

GET/segments

Parâmetros de consulta

pageintegerpadrão: 1
Número da página, a partir de 1.
limitintegerpadrão: 10
Segmentos por página, de 1 a 100.
with_countsbooleanpadrão: false
Adiciona contacts_count e subscribed_count a cada segmento. A contagem avalia todos os segmentos da página, então ela vem desativada por padrão.
matchstring

all (padrão) exige todos os filtros. or corresponde a qualquer filtro. Consulte Filtragem.

orderstring

Chave de ordenação desta lista. Consulte as chaves de ordenação abaixo.

directionstring

asc ou desc.

Chaves de filtro

Os filtros usam parâmetros de consulta key.condition=value, por exemplo, name.contains=customers ou created_at.after=2026-09-01. Consulte Filtragem para as condições de cada tipo.

Chave Tipo Observações
name string
created_at date
updated_at date

Chaves de ordenação para order: name, created_at, updated_at.

Retorno

dataobject[]
Objetos de segmento desta página. contacts_count e subscribed_count só são incluídos com with_counts.
total_recordsinteger
Número de segmentos que correspondem à consulta.
usageobject
Os segmentos do workspace em relação ao plano: used (todos os segmentos, rastreados ou não), limit (segmentos que o plano inclui) e tracking_allowed (se o plano inclui segmentos rastreados). Consulte Limites.
next_page_urlstring | null
Caminho da próxima página, ou null na última página. Ele leva apenas page e limit; adicione de novo a sua busca e os seus filtros ao segui-lo.
previous_page_urlstring | null
Caminho da página anterior, ou null na primeira página.
GET/segments
Terminal
curl -G https://api.emailit.com/v2/segments \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -d with_counts=true
JSON
{
  "data": [
    {
      "object": "segment",
      "id": "seg_2nYs9Kd1Lq3vB8wXcE4fT7uRm0p",
      "name": "Pro customers renewing soon",
      "description": "Pro and Enterprise plans that renew in the next 30 days.",
      "audience_ids": ["aud_2nYs8Qm4Hc1Zx7Vb3Ne6Tg9Lk2a"],
      "conditions": {
        "match": "all",
        "groups": [
          {
            "match": "all",
            "rules": [
              { "field": "custom_fields.plan", "operator": "in", "value": ["pro", "enterprise"] },
              { "field": "custom_fields.renews_on", "operator": "in_next_days", "value": 30 }
            ]
          }
        ]
      },
      "tracked": true,
      "tracking": {
        "status": "active",
        "synced_at": "2026-10-18T00:30:04.211000+00:00"
      },
      "contacts_count": 412,
      "subscribed_count": 398,
      "created_at": "2026-10-02T09:14:03.551000+00:00",
      "updated_at": "2026-10-02T09:14:03.551000+00:00"
    }
  ],
  "total_records": 1,
  "usage": {
    "used": 1,
    "limit": 10,
    "tracking_allowed": true
  },
  "next_page_url": null,
  "previous_page_url": null
}

Excluir um segmento

Exclui um segmento. Requer uma chave de API com escopo full.

  • Um segmento que uma campanha usa enquanto ela está agendada, na fila, em envio ou em teste não pode ser excluído. Altere primeiro os destinatários da campanha.
  • Um segmento não pode ser excluído enquanto qualquer automação não excluída, em qualquer status, o usar: em um gatilho Added to segment ou Removed from segment, em uma meta, etapa Wait until ou condição de saída sobre esses eventos, ou em uma regra Segment de uma condição. Altere primeiro essas automações.
  • As campanhas em rascunho que enviam para o segmento o perdem dos seus destinatários, e removed_from_campaigns informa quantas são. Os rascunhos que deixam o segmento de fora mantêm a exclusão, então não podem ser enviados até você substituí-la: descartá-la enviaria a campanha para as pessoas que você queria deixar de fora. As campanhas enviadas, canceladas e arquivadas mantêm a referência como histórico.
  • No caso de um segmento rastreado, os membros armazenados e o histórico de crescimento dele também são excluídos.
DELETE/segments/{id}

Parâmetros de caminho

idstringobrigatório
O ID do segmento (seg_…).

Retorno

objectstring
Sempre segment.
idstring
ID do segmento excluído.
namestring
O nome dele.
deletedboolean
Sempre true.
removed_from_campaignsinteger
Número de campanhas em rascunho que não enviam mais para o segmento.
Status Quando
404 O segmento não existe.
409 Uma campanha agendada, na fila, em envio ou em teste usa o segmento, ou uma automação parte dele. A mensagem informa os nomes delas.
DELETE/segments/{id}
Terminal
curl -X DELETE https://api.emailit.com/v2/segments/seg_2nYs9Kd1Lq3vB8wXcE4fT7uRm0p \
  -H "Authorization: Bearer $EMAILIT_API_KEY"
JSON
{
  "object": "segment",
  "id": "seg_2nYs9Kd1Lq3vB8wXcE4fT7uRm0p",
  "name": "Pro customers renewing soon",
  "deleted": true,
  "removed_from_campaigns": 1
}

Listar os contatos de um segmento

Retorna os contatos que correspondem ao segmento no momento da chamada, dos mais recentes para os mais antigos. Requer uma chave de API com escopo full.

GET/segments/{id}/contacts

Parâmetros de caminho

idstringobrigatório
O ID do segmento (seg_…).

Parâmetros de consulta

pageintegerpadrão: 1
Número da página, a partir de 1.
limitintegerpadrão: 25
Contatos por página, de 1 a 100.
matchstring

all (padrão) exige todos os filtros. or corresponde a qualquer filtro. Consulte Filtragem.

orderstring

Chave de ordenação desta lista. Consulte as chaves de ordenação abaixo.

directionstring

asc ou desc.

Chaves de filtro

Os contatos de um segmento aceitam as mesmas chaves de filtro e de ordenação que Listar contatos, aplicadas sobre o segmento, por exemplo, email.ends_with=acme.com.

Os filtros de listagem são um único nível de parâmetros de consulta key.condition=value. Consulte Filtragem para match, order, direction e a lista de condições por tipo.

Chaves de filtro

ChaveTipoCondiçõesObservações
emailstringexact, not_exact, contains, not_contains, starts_with, ends_with, empty, not_empty
first_namestringexact, not_exact, contains, not_contains, starts_with, ends_with, empty, not_empty
last_namestringexact, not_exact, contains, not_contains, starts_with, ends_with, empty, not_empty
namestringexact, not_exact, contains, not_contains, starts_with, ends_with, empty, not_emptyNome e sobrenome juntos, sem espaços nas extremidades.
audiencesstringexact, not_exact, contains, not_contains, starts_with, ends_with, empty, not_emptyCompara com o nome da lista do contato que vem primeiro em ordem alfabética.
created_atdateexact, before, after, empty, not_empty
updated_atdateexact, before, after, empty, not_empty
unsubscribedbooleanexact, not_exact
audience_idstringexact, not_exactApenas exact e not_exact. O valor é um ID de lista de contatos (aud_...).
custom_fields.*stringexact, not_exact, contains, not_contains, starts_with, ends_with, empty, not_emptySubstitua * pela chave de um campo personalizado, por exemplo custom_fields.company.contains=Acme.

Chaves de ordenação

Passe em order uma destas chaves e em direction o valor asc ou desc: email, first_name, last_name, name, audiences, created_at, updated_at, unsubscribed

Retorno

dataobject[]
Os contatos desta página, cada um com object, id, email, first_name, last_name, custom_fields, unsubscribed, audiences (id, name, subscribed), created_at e updated_at. Os contatos de um segmento rastreado também têm joined_at.
data[].joined_atstring | null
Apenas segmentos rastreados: quando começou a permanência atual do contato no segmento. null até o rastreamento registrar o contato, por exemplo logo depois que ele passou a corresponder, enquanto o segmento está em syncing ou enquanto o rastreamento está em paused.
total_recordsinteger
Número de contatos que correspondem ao segmento, à busca e aos filtros.
subscribed_countinteger
Para quantos deles as campanhas podem enviar: não descadastrados globalmente e inscritos em pelo menos uma lista.
next_page_urlstring | null
Caminho da próxima página, ou null na última página. Ele leva page, limit e search; adicione de novo os seus filtros ao segui-lo.
previous_page_urlstring | null
Caminho da página anterior, ou null na primeira página.

Retorna 404 se o segmento não existir.

GET/segments/{id}/contacts
Terminal
curl -G https://api.emailit.com/v2/segments/seg_2nYs9Kd1Lq3vB8wXcE4fT7uRm0p/contacts \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -d email.ends_with=acme.com
JSON
{
  "data": [
    {
      "object": "contact",
      "id": "con_2nYs7Ab3Kd9Lm1Qw5Er8Ty2Ui4o",
      "email": "ada@acme.com",
      "first_name": "Ada",
      "last_name": "Lovelace",
      "custom_fields": {
        "plan": "pro",
        "renews_on": "2026-10-20"
      },
      "unsubscribed": false,
      "audiences": [
        {
          "id": "aud_2nYs8Qm4Hc1Zx7Vb3Ne6Tg9Lk2a",
          "name": "Customers",
          "subscribed": true
        }
      ],
      "created_at": "2026-03-11T08:00:00.000000+00:00",
      "updated_at": "2026-09-30T16:42:10.000000+00:00",
      "joined_at": "2026-10-03T00:30:02.874000+00:00"
    }
  ],
  "total_records": 1,
  "subscribed_count": 1,
  "next_page_url": null,
  "previous_page_url": null
}

Obter o crescimento de um segmento

Retorna o histórico de um segmento rastreado: uma linha por dia UTC, dos mais antigos para os mais recentes, terminando hoje. São os dados por trás do gráfico Growth na página do segmento. Requer uma chave de API com escopo full.

O histórico começa quando o rastreamento começa. Os contatos registrados pela primeira contagem depois que o segmento foi criado, ou depois que o rastreamento foi retomado, contam como membros, mas não como entradas.

GET/segments/{id}/growth

Parâmetros de caminho

idstringobrigatório
O ID do segmento (seg_…).

Parâmetros de consulta

daysintegerpadrão: 30
Número de dias a retornar, de 1 a 365, terminando hoje.

Retorno

objectstring
Sempre segment_growth.
segment_idstring
O ID do segmento.
dataobject[]
Uma linha por dia.
data[].datestring
O dia em UTC, YYYY-MM-DD.
data[].members_countinteger | null
Membros no fim do dia, ou a contagem mais recente para hoje. Os dias sem uma nova contagem repetem o valor anterior, por exemplo enquanto o rastreamento está pausado. null antes de o rastreamento começar.
data[].joined_countinteger
Contatos que entraram no segmento naquele dia.
data[].left_countinteger
Contatos que saíram do segmento naquele dia.
Status Quando
404 O segmento não existe.
422 O segmento não é rastreado.
GET/segments/{id}/growth
Terminal
curl -G https://api.emailit.com/v2/segments/seg_2nYs9Kd1Lq3vB8wXcE4fT7uRm0p/growth \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -d days=7
JSON
{
  "object": "segment_growth",
  "segment_id": "seg_2nYs9Kd1Lq3vB8wXcE4fT7uRm0p",
  "data": [
    { "date": "2026-10-12", "members_count": null, "joined_count": 0, "left_count": 0 },
    { "date": "2026-10-13", "members_count": 380, "joined_count": 0, "left_count": 0 },
    { "date": "2026-10-14", "members_count": 391, "joined_count": 14, "left_count": 3 },
    { "date": "2026-10-15", "members_count": 391, "joined_count": 0, "left_count": 0 },
    { "date": "2026-10-16", "members_count": 402, "joined_count": 12, "left_count": 1 },
    { "date": "2026-10-17", "members_count": 405, "joined_count": 6, "left_count": 3 },
    { "date": "2026-10-18", "members_count": 412, "joined_count": 9, "left_count": 2 }
  ]
}

Pré-visualizar um segmento

Verifica uma definição de segmento sem salvá-la: retorna quantos contatos correspondem a ela e uma amostra deles. A definição é validada como em Criar um segmento, e uma pré-visualização não conta para o limite de segmentos do plano. Requer uma chave de API com escopo full.

POST/segments/preview

Parâmetros do corpo

audience_idsstring[]
IDs das listas de contatos que o segmento usaria como origem. Vazio ou omitido significa todos os contatos.
conditionsobject
As regras. Consulte Criar um segmento.
limitintegerpadrão: 10
Número de contatos de amostra, de 1 a 25.

Retorno

objectstring
Sempre segment_preview.
audience_idsstring[]
As listas de contatos de origem, sem duplicatas.
conditionsobject
As regras como seriam salvas: um { match, rules } plano vira um único grupo, e os grupos vazios são descartados.
contacts_countinteger
Contatos que correspondem à definição.
subscribed_countinteger
Para quantos deles as campanhas podem enviar.
contactsobject[]
Os contatos correspondentes mais recentes, no mesmo formato de Listar os contatos de um segmento.

Retorna 422 com errors indexado pelo caminho do campo se a definição for inválida.

POST/segments/preview
Terminal
curl -X POST https://api.emailit.com/v2/segments/preview \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "conditions": { "rules": [{ "field": "email_domain", "operator": "equals", "value": "acme.com" }] },
    "limit": 5
  }'
JSON
{
  "object": "segment_preview",
  "audience_ids": [],
  "conditions": {
    "match": "all",
    "groups": [
      {
        "match": "all",
        "rules": [
          { "field": "email_domain", "operator": "equals", "value": "acme.com" }
        ]
      }
    ]
  },
  "contacts_count": 8,
  "subscribed_count": 8,
  "contacts": [
    {
      "object": "contact",
      "id": "con_2nYs7Ab3Kd9Lm1Qw5Er8Ty2Ui4o",
      "email": "ada@acme.com",
      "first_name": "Ada",
      "last_name": "Lovelace",
      "custom_fields": {
        "plan": "pro",
        "renews_on": "2026-10-20"
      },
      "unsubscribed": false,
      "audiences": [
        {
          "id": "aud_2nYs8Qm4Hc1Zx7Vb3Ne6Tg9Lk2a",
          "name": "Customers",
          "subscribed": true
        }
      ],
      "created_at": "2026-03-11T08:00:00.000000+00:00",
      "updated_at": "2026-09-30T16:42:10.000000+00:00"
    }
  ]
}

Listar os campos de segmentos

Retorna os campos que as regras de segmento podem usar neste workspace: os campos do contato, cada campo personalizado (com o tipo definido pelo tipo do campo personalizado), a participação em listas, os dados de compra e o engajamento com campanhas. Requer uma chave de API com escopo full.

GET/segments/fields

Retorno

dataobject[]
Um item por campo.
data[].keystring
O valor a usar como field de uma regra, por exemplo email_domain ou custom_fields.plan.
data[].labelstring
Nome de exibição. Nos campos personalizados, o nome do campo personalizado.
data[].typestring
string, number, date, datetime, boolean, enum, multi, audience, metric, moment, purchase, view, cart, coupon ou campaign_activity. Consulte Criar um segmento. Os campos de atividade, como purchased, recebem um objeto como valor; consulte Regras de atividade.
data[].groupstring
contact, custom_fields, audiences, commerce (dados de compra) ou engagement (atividade em campanhas).
data[].operatorsstring[]
Operadores que o campo aceita.
data[].valuesobject[]
Valores permitidos, como value e label: as opções dos campos personalizados de seleção e de seleção múltipla, subscribed e unsubscribed para status e as listas de contatos do workspace para audience. Ausente nos outros campos.
GET/segments/fields
Terminal
curl https://api.emailit.com/v2/segments/fields \
  -H "Authorization: Bearer $EMAILIT_API_KEY"
JSON
{
  "data": [
    {
      "key": "email",
      "label": "Email",
      "type": "string",
      "group": "contact",
      "operators": ["equals", "not_equals", "contains", "not_contains", "starts_with", "ends_with", "in", "not_in", "is_set", "is_not_set"]
    },
    {
      "key": "status",
      "label": "Subscription status",
      "type": "enum",
      "group": "contact",
      "operators": ["equals", "not_equals"],
      "values": [
        { "value": "subscribed", "label": "Subscribed" },
        { "value": "unsubscribed", "label": "Unsubscribed" }
      ]
    },
    {
      "key": "audience",
      "label": "Audience",
      "type": "audience",
      "group": "audiences",
      "operators": ["in", "not_in"],
      "values": [
        { "value": "aud_2nYs8Qm4Hc1Zx7Vb3Ne6Tg9Lk2a", "label": "Customers" }
      ]
    },
    {
      "key": "purchased",
      "label": "Purchased",
      "type": "purchase",
      "group": "commerce",
      "operators": [
        "has",
        "has_not"
      ]
    },
    {
      "key": "custom_fields.renews_on",
      "label": "Renews on",
      "type": "date",
      "group": "custom_fields",
      "operators": ["on", "before", "after", "between", "in_last_days", "more_than_days_ago", "in_next_days", "is_set", "is_not_set"]
    }
  ]
}

Esta página foi útil?

Obrigado pelo feedback.

Obrigado, lemos todas as mensagens.