Segmentos
Salve filtros sobre os seus contatos, liste quem corresponde a eles e acompanhe os segmentos rastreados ao longo do tempo.
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.
/segmentsParâmetros do corpo
namestringobrigatóriodescriptionstring | nullaudience_idsstring[]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.conditionsobjecttrackedbooleanpadrão: falseCondiçõ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:
{
"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) ouany, 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_containsenot_intambém correspondem a contatos que não têm valor.in,not_inecontains_allrecebem uma lista de até 100 valores. Os valores de texto podem ter até 500 caracteres.betweenrecebe[from, to], com os dois extremos incluídos: dois números ou duas datasYYYY-MM-DD.on,beforeeafterrecebem uma dataYYYY-MM-DD.beforeeafternão incluem esse dia.in_last_days,more_than_days_agoein_next_daysrecebem 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_ateupdated_atusam horários exatos, entãoin_last_dayscom7significa as últimas 7 × 24 horas.is_set,is_not_set,is_trueeis_falsenão recebem valor.is_truecorresponde atrue,1,yeseon;is_falsecorresponde afalse,0,noeoff.- 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.
{
"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. |
{
"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"
}{
"error": "plan_required",
"message": "Tracked segments are included with Pro and Business.",
"required_plan": "pro"
}{
"message": "Validation failed. conditions.groups.0.rules.1.value: Enter a whole number of days between 1 and 3650.",
"errors": {
"conditions.groups.0.rules.1.value": [
"Enter a whole number of days between 1 and 3650."
]
}
}{
"error": "Pay as you go includes 3 segments.",
"message": "Pay as you go includes 3 segments.",
"usage": {
"used": 3,
"limit": 3
}
}Obter um segmento
Obtém um segmento e conta os contatos dele no momento da chamada. Requer uma chave de API com escopo full.
/segments/{id}Parâmetros de caminho
idstringobrigatórioseg_…).Retorno
Retorna o objeto de segmento.
objectstringsegment.idstringseg_.namestringdescriptionstring | nullaudience_idsstring[]conditionsobject{ "match", "groups": [{ "match", "rules": [...] }] }. Consulte Criar um segmento.trackedbooleantrackingobject | nullnull para segmentos que não são rastreados. Para segmentos rastreados:
status:activequando os membros são mantidos atualizados,syncingenquanto o Emailit registra os membros atuais depois que o segmento foi criado ou que o rastreamento foi retomado, oupausedquando 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, ounullantes da primeira comparação.
contacts_countintegersubscribed_countintegercontacts_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_atstringRetorna 404 se o segmento não existir.
{
"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"
}{
"error": "Segment not found"
}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.
/segments/{id}Parâmetros de caminho
idstringobrigatórioseg_…).Parâmetros do corpo
namestringdescriptionstring | nullnull ou uma string vazia a apaga.audience_idsstring[][] significa todos os contatos do workspace.conditionsobjecttrackedbooleanRetorno
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. |
{
"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"
}{
"error": "Segment not found"
}{
"message": "Validation failed. tracked: Tracking is chosen when a segment is created and can't be changed. Create a new segment instead.",
"errors": {
"tracked": [
"Tracking is chosen when a segment is created and can't be changed. Create a new segment instead."
]
}
}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.
/segmentsParâmetros de consulta
pageintegerpadrão: 1limitintegerpadrão: 10searchstringwith_countsbooleanpadrão: falsecontacts_count e subscribed_count a cada segmento. A contagem avalia todos os segmentos da página, então ela vem desativada por padrão.matchstringall (padrão) exige todos os filtros. or corresponde a qualquer filtro. Consulte Filtragem.
orderstringChave de ordenação desta lista. Consulte as chaves de ordenação abaixo.
directionstringasc 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[]contacts_count e subscribed_count só são incluídos com with_counts.total_recordsintegerusageobjectused (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 | nullnull 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 | nullnull na primeira página.{
"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_campaignsinforma 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.
/segments/{id}Parâmetros de caminho
idstringobrigatórioseg_…).Retorno
objectstringsegment.idstringnamestringdeletedbooleantrue.removed_from_campaignsinteger| 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. |
{
"object": "segment",
"id": "seg_2nYs9Kd1Lq3vB8wXcE4fT7uRm0p",
"name": "Pro customers renewing soon",
"deleted": true,
"removed_from_campaigns": 1
}{
"error": "This segment is used by campaigns that are scheduled or sending: October launch. Change their recipients first.",
"message": "This segment is used by campaigns that are scheduled or sending: October launch. Change their recipients first."
}{
"error": "This segment is used by automations: Renewal reminder. Change their triggers, conditions or exit conditions first.",
"message": "This segment is used by automations: Renewal reminder. Change their triggers, conditions or exit conditions first."
}{
"error": "Segment not found"
}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.
/segments/{id}/contactsParâmetros de caminho
idstringobrigatórioseg_…).Parâmetros de consulta
pageintegerpadrão: 1limitintegerpadrão: 25searchstringmatchstringall (padrão) exige todos os filtros. or corresponde a qualquer filtro. Consulte Filtragem.
orderstringChave de ordenação desta lista. Consulte as chaves de ordenação abaixo.
directionstringasc 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
| Chave | Tipo | Condições | Observações |
|---|---|---|---|
email | string | exact, not_exact, contains, not_contains, starts_with, ends_with, empty, not_empty | |
first_name | string | exact, not_exact, contains, not_contains, starts_with, ends_with, empty, not_empty | |
last_name | string | exact, not_exact, contains, not_contains, starts_with, ends_with, empty, not_empty | |
name | string | exact, not_exact, contains, not_contains, starts_with, ends_with, empty, not_empty | Nome e sobrenome juntos, sem espaços nas extremidades. |
audiences | string | exact, not_exact, contains, not_contains, starts_with, ends_with, empty, not_empty | Compara com o nome da lista do contato que vem primeiro em ordem alfabética. |
created_at | date | exact, before, after, empty, not_empty | |
updated_at | date | exact, before, after, empty, not_empty | |
unsubscribed | boolean | exact, not_exact | |
audience_id | string | exact, not_exact | Apenas exact e not_exact. O valor é um ID de lista de contatos (aud_...). |
custom_fields.* | string | exact, not_exact, contains, not_contains, starts_with, ends_with, empty, not_empty | Substitua * 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[]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 | nullnull 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_recordsintegersubscribed_countintegernext_page_urlstring | nullnull na última página. Ele leva page, limit e search; adicione de novo os seus filtros ao segui-lo.previous_page_urlstring | nullnull na primeira página.Retorna 404 se o segmento não existir.
{
"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
}{
"error": "Segment not found"
}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.
/segments/{id}/growthParâmetros de caminho
idstringobrigatórioseg_…).Parâmetros de consulta
daysintegerpadrão: 30Retorno
objectstringsegment_growth.segment_idstringdataobject[]data[].datestringYYYY-MM-DD.data[].members_countinteger | nullnull antes de o rastreamento começar.data[].joined_countintegerdata[].left_countinteger| Status | Quando |
|---|---|
404 |
O segmento não existe. |
422 |
O segmento não é rastreado. |
{
"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 }
]
}{
"error": "Growth is recorded for tracked segments only.",
"message": "Growth is recorded for tracked segments only."
}{
"error": "Segment not found"
}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.
/segments/previewParâmetros do corpo
audience_idsstring[]conditionsobjectlimitintegerpadrão: 10Retorno
objectstringsegment_preview.audience_idsstring[]conditionsobject{ match, rules } plano vira um único grupo, e os grupos vazios são descartados.contacts_countintegersubscribed_countintegercontactsobject[]Retorna 422 com errors indexado pelo caminho do campo se a definição for inválida.
{
"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"
}
]
}{
"message": "Validation failed. conditions.groups.0.rules.0.operator: \"greater_than\" does not apply to Email domain.",
"errors": {
"conditions.groups.0.rules.0.operator": [
"\"greater_than\" does not apply to Email domain."
]
}
}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.
/segments/fieldsRetorno
dataobject[]data[].keystringfield de uma regra, por exemplo email_domain ou custom_fields.plan.data[].labelstringdata[].typestringstring, 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[].groupstringcontact, custom_fields, audiences, commerce (dados de compra) ou engagement (atividade em campanhas).data[].operatorsstring[]data[].valuesobject[]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.{
"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"]
}
]
}