Saltar al contenido
Docs

Guarda filtros sobre tus contactos, lista quién coincide con ellos y sigue la evolución de los segmentos con seguimiento.

URL basehttps://api.emailit.com/v2AutenticaciónErroresLímites de velocidad

Crear un segmento

Crea un segmento: un filtro guardado sobre los contactos del espacio de trabajo. Requiere una clave de API con el permiso full.

Un segmento contiene los contactos de su origen (los suscriptores de audience_ids, o todos los contactos si está vacío) que cumplen sus conditions. La pertenencia se evalúa en directo cada vez que el segmento se cuenta, se lista, se previsualiza o lo usa una campaña al enviarse. Consulta Segmentos.

Cada plan incluye un número de segmentos por espacio de trabajo, con seguimiento o sin él. Consulta Límites.

POST/segments

Parámetros del cuerpo

namestringobligatorio
El nombre del segmento, de hasta 191 caracteres.
descriptionstring | null
Una nota para tu equipo, de hasta 1000 caracteres.
audience_idsstring[]
El origen: los ID de listas de contactos (aud_…) de este espacio de trabajo, hasta 100. El segmento solo contiene contactos suscritos al menos a una de ellas. Si está vacío o se omite, se usan todos los contactos del espacio de trabajo.
conditionsobject
Las reglas que tienen que cumplir los contactos, descritas en Condiciones. Omítelo para incluir a todos los contactos del origen.
trackedbooleanpor defecto: false
Guarda los miembros del segmento para que las entradas y salidas de contactos se conviertan en eventos para automatizaciones y webhooks. Incluido en Pro, Business y Custom. Lo eliges aquí y no puedes cambiarlo después. Consulta Segmentos con seguimiento.

Condiciones

conditions contiene grupos de reglas. El match del nivel superior une los grupos, y el match de cada grupo une sus reglas:

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 es all (por defecto) o any, en el nivel superior y en cada grupo.
  • Omite conditions, o no envíes grupos, para incluir a todos los contactos del origen. Los grupos vacíos se descartan.
  • También se acepta la forma plana { "match": "any", "rules": [...] }, que se guarda como un solo grupo.
  • Un segmento puede tener hasta 10 grupos y 50 reglas en total.

Campos

Campo Tipo Notas
email string
email_domain string La parte de la dirección que va después de @.
first_name, last_name string
status enum subscribed (no se ha dado de baja de forma global y está suscrito al menos a una lista, así que las campañas pueden llegar al contacto) o unsubscribed. Operadores: equals, not_equals.
created_at, updated_at datetime Cuándo se creó el contacto o cuándo cambió por última vez, comparado en UTC.
audience audience Pertenencia con suscripción. in coincide con los contactos suscritos a cualquiera de los ID de lista, y not_in, con los contactos que no están suscritos a ninguna de ellas.
tags tags Las etiquetas del contacto. Los valores se comparan en minúsculas.
score score La puntuación de lead del contacto.
custom_fields.<key> según el campo Los campos de texto son string; los numéricos, number; los de fecha, date (YYYY-MM-DD); los booleanos, boolean; los de selección, enum, y los de selección múltiple, multi.
orders_count, total_spent, average_order_value metric A partir de los pedidos del contacto. 0 en los contactos sin pedidos. Los importes están en la moneda de los pedidos del contacto.
first_order_at, last_order_at moment Sin valor en los contactos sin pedidos.
expected_next_order_at moment El último pedido más el intervalo medio del contacto entre pedidos. Tiene valor a partir del segundo pedido y puede estar en el futuro.
churn_risk enum low, medium o high: el tiempo transcurrido desde el último pedido comparado con el intervalo habitual del contacto (como mínimo 14 días), o con 90 días para quienes solo han comprado una vez. Sin valor si no hay pedidos.
last_active_at moment La última vez que el script de seguimiento vio al contacto en tu web.
purchased purchase Pedidos; consulta Reglas de actividad.
viewed_product view Visualizaciones de productos registradas por el script de seguimiento.
cart cart Carritos abiertos y abandonados.
used_coupon coupon Pedidos en los que se usó un código de cupón.
campaign_activity campaign_activity Emails de campaña recibidos, abiertos o con clic.

Listar los campos de segmento devuelve los campos de tu espacio de trabajo, incluidos sus campos personalizados y sus listas, con los operadores que acepta cada uno.

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 (tiene alguno), contains_all (los tiene todos), not_in (no tiene ninguno), is_set, is_not_set
audience in, not_in
tags in (tiene alguna), contains_all (las tiene todas), not_in (no tiene ninguna), is_set (tiene alguna etiqueta), is_not_set (no tiene etiquetas)
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

  • Las comparaciones de texto en los campos string no distinguen mayúsculas y minúsculas. Los valores de selección y de selección múltiple tienen que coincidir exactamente.
  • not_equals, not_contains y not_in también coinciden con los contactos que no tienen ningún valor.
  • in, not_in y contains_all aceptan una lista de hasta 100 valores. Los valores de texto pueden tener hasta 500 caracteres.
  • between acepta [from, to], ambos incluidos: dos números o dos fechas YYYY-MM-DD.
  • on, before y after aceptan una fecha YYYY-MM-DD. before y after no incluyen ese día.
  • in_last_days, more_than_days_ago e in_next_days aceptan un número entero de días de 1 a 3650, contados desde el momento en que se evalúa el segmento. Los campos personalizados de fecha comparan días naturales en UTC; created_at y updated_at usan horas exactas, así que in_last_days con 7 significa las últimas 7 × 24 horas.
  • is_set, is_not_set, is_true e is_false no aceptan ningún valor. is_true coincide con true, 1, yes y on; is_false coincide con false, 0, no y off.
  • Una regla guardada que ya no es aplicable, por ejemplo porque su campo personalizado ha cambiado de tipo, no coincide con ningún contacto. Las reglas sobre un campo personalizado eliminado siguen funcionando con los valores que aún tienen los contactos, pero las reglas nuevas tienen que usar un campo existente.

Reglas de actividad

purchased, viewed_product, cart, used_coupon y campaign_activity aceptan un objeto como value. Todas las claves son opcionales.

Campo Claves del valor
purchased days: solo los pedidos realizados en los últimos N días. product_ids: pedidos con cualquiera de estos productos (los ID de producto de tu tienda). categories: pedidos con un producto de cualquiera de estas categorías. min_count: al menos este número de pedidos que coinciden (por defecto 1, hasta 1000). Los pedidos cancelados no cuentan.
viewed_product days, product_ids, categories y min_count, como en la fila anterior, contando visualizaciones de productos.
cart days, solo con has_abandoned_cart: carritos abandonados en los últimos N días. has_open_cart coincide con un carrito activo, y has_no_open_cart, con los contactos sin ningún carrito activo ni abandonado.
used_coupon days y coupon: la clave de un cupón. Sin coupon, cuenta cualquier código.
campaign_activity campaign_id: una campaña (cmp_...); si falta, cualquier campaña. days: solo los últimos N días; si falta, desde siempre.

days es un número entero de 1 a 3650. has_not es lo contrario de has con el mismo 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 y received_not_clicked coinciden con los contactos que han recibido al menos un email de campaña que cumple la regla y no han abierto ninguno o no han hecho clic en ninguno, respectivamente. Las aperturas son aproximadas: Apple Mail carga las imágenes de todos los emails que recibe.

Devuelve

Devuelve 201 Created con el objeto de segmento, incluidos contacts_count y subscribed_count. Un segmento con seguimiento nuevo empieza con tracking.status en syncing mientras Emailit registra sus miembros actuales.

Código Cuándo
400 Falta name o un campo tiene un tipo incorrecto.
403 tracked es true y el plan no incluye segmentos con seguimiento. El cuerpo es {"error": "plan_required", "required_plan": "pro", ...}.
422 Un campo o una regla no son válidos: errors usa su ruta como clave, por ejemplo conditions.groups.0.rules.1.value, y message repite el primer problema. También se devuelve cuando el espacio de trabajo ha alcanzado el límite de segmentos de su plan; ese cuerpo incluye usage.used y 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"
}

Obtener un segmento

Obtiene un segmento y cuenta sus contactos en el momento de la llamada. Requiere una clave de API con el permiso full.

GET/segments/{id}

Parámetros de ruta

idstringobligatorio
El ID del segmento (seg_…).

Devuelve

Devuelve el objeto de segmento.

objectstring
Siempre segment.
idstring
El ID del segmento, con el prefijo seg_.
namestring
El nombre del segmento.
descriptionstring | null
Una nota para tu equipo.
audience_idsstring[]
Las listas de contactos de origen. Si está vacío, se usan todos los contactos del espacio de trabajo.
conditionsobject
Las reglas, con la forma { "match", "groups": [{ "match", "rules": [...] }] }. Consulta Crear un segmento.
trackedboolean
Si el segmento guarda sus miembros e informa de las entradas y salidas. Consulta Segmentos con seguimiento.
trackingobject | null

null en los segmentos sin seguimiento. En los segmentos con seguimiento:

  • status: active cuando los miembros se mantienen al día, syncing mientras Emailit registra los miembros actuales después de crear el segmento o de reanudar el seguimiento, o paused cuando el plan del espacio de trabajo ya no incluye segmentos con seguimiento.
  • synced_at: la última vez que se comparó todo el segmento con sus reglas, o null antes de la primera comparación.
contacts_countinteger
Los contactos que coinciden en este momento.
subscribed_countinteger
La parte de contacts_count a la que pueden enviar las campañas: los contactos que no se han dado de baja de forma global y están suscritos al menos a una lista de contactos. Las direcciones bloqueadas se siguen contando.
created_at, updated_atstring
Las marcas de tiempo en UTC.

Devuelve 404 si el segmento no existe.

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

Actualizar un segmento

Actualiza los campos que envías y deja los demás sin cambios. audience_ids y conditions se sustituyen por completo. Requiere una clave de API con el permiso full.

Las campañas evalúan un segmento cuando se envían, así que las reglas nuevas se aplican a todas las campañas que aún no se han enviado, también a las programadas.

En un segmento con seguimiento, cambiar audience_ids o conditions compara los miembros guardados con las reglas nuevas. Los contactos que entran o salen por el cambio envían eventos segment.contact_added y segment.contact_removed con reason en segment_updated. Los webhooks los reciben, pero no inician automatizaciones.

POST/segments/{id}

Parámetros de ruta

idstringobligatorio
El ID del segmento (seg_…).

Parámetros del cuerpo

namestring
El nombre nuevo, de hasta 191 caracteres. No puede estar vacío.
descriptionstring | null
Una nota para tu equipo, de hasta 1000 caracteres. null o una cadena vacía la borran.
audience_idsstring[]
Los ID de las listas de contactos de origen. [] significa todos los contactos del espacio de trabajo.
conditionsobject
Las reglas. Consulta Crear un segmento.
trackedboolean
Solo se acepta con el valor actual del segmento. El seguimiento se elige al crear un segmento; para cambiarlo, crea un segmento nuevo.

Devuelve

Devuelve el objeto de segmento actualizado, con los recuentos recalculados.

Código Cuándo
404 El segmento no existe.
422 Un campo o una regla no son válidos, o tracked es distinto del valor actual del segmento. errors usa la ruta del campo como clave.
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

Devuelve los segmentos del espacio de trabajo, del más reciente al más antiguo, con cuántos de los segmentos del plan están en uso. Requiere una clave de API con el permiso full.

GET/segments

Parámetros de consulta

pageintegerpor defecto: 1
El número de página, empezando por 1.
limitintegerpor defecto: 10
Los segmentos por página, de 1 a 100.
with_countsbooleanpor defecto: false
Añade contacts_count y subscribed_count a cada segmento. El recuento evalúa todos los segmentos de la página, así que está desactivado por defecto.
matchstring

all (por defecto) exige que se cumplan todos los filtros. or coincide con cualquier filtro. Consulta Filtrado.

orderstring

Clave de ordenación de esta lista. Consulta las claves de ordenación más abajo.

directionstring

asc o desc.

Claves de filtro

Los filtros usan parámetros de consulta key.condition=value, por ejemplo name.contains=customers o created_at.after=2026-09-01. Para las condiciones de cada tipo, consulta Filtrado y ordenación.

Clave Tipo Notas
name string
created_at date
updated_at date

Claves de orden para order: name, created_at, updated_at.

Devuelve

dataobject[]
Los objetos de segmento de esta página. contacts_count y subscribed_count solo se incluyen con with_counts.
total_recordsinteger
El número de segmentos que coinciden con la consulta.
usageobject
Los segmentos del espacio de trabajo frente a su plan: used (todos los segmentos, con seguimiento o sin él), limit (los segmentos que incluye el plan) y tracking_allowed (si el plan incluye segmentos con seguimiento). Consulta Límites.
next_page_urlstring | null
La ruta de la página siguiente, o null en la última página. Solo lleva page y limit; vuelve a añadir tu búsqueda y tus filtros cuando la sigas.
previous_page_urlstring | null
La ruta de la página anterior, o null en la primera 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
}

Eliminar un segmento

Elimina un segmento. Requiere una clave de API con el permiso full.

  • Un segmento que usa una campaña mientras está programada, en cola, enviándose o en prueba no se puede eliminar. Cambia antes los destinatarios de la campaña.
  • Un segmento no se puede eliminar mientras lo use alguna automatización no eliminada, en cualquier estado: en un disparador Added to segment o Removed from segment, en un objetivo, un paso Wait until o una condición de salida sobre esos eventos, o en una regla Segment de una condición. Cambia antes esas automatizaciones.
  • Los borradores de campaña que se envían al segmento lo pierden de sus destinatarios, y removed_from_campaigns indica cuántos son. Los borradores que excluyen el segmento conservan la exclusión, así que no se pueden enviar hasta que la sustituyas: si se descartara, la campaña llegaría a las personas que querías dejar fuera. Las campañas enviadas, canceladas y archivadas conservan la referencia como historial.
  • En un segmento con seguimiento, también se eliminan sus miembros guardados y su historial de crecimiento.
DELETE/segments/{id}

Parámetros de ruta

idstringobligatorio
El ID del segmento (seg_…).

Devuelve

objectstring
Siempre segment.
idstring
El ID del segmento eliminado.
namestring
Su nombre.
deletedboolean
Siempre true.
removed_from_campaignsinteger
El número de borradores de campaña que ya no se envían al segmento.
Código Cuándo
404 El segmento no existe.
409 Una campaña programada, en cola, enviándose o en prueba usa el segmento, o una automatización parte de él. El mensaje las nombra.
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 los contactos de un segmento

Devuelve los contactos que coinciden con el segmento en el momento de la llamada, del más reciente al más antiguo. Requiere una clave de API con el permiso full.

GET/segments/{id}/contacts

Parámetros de ruta

idstringobligatorio
El ID del segmento (seg_…).

Parámetros de consulta

pageintegerpor defecto: 1
El número de página, empezando por 1.
limitintegerpor defecto: 25
Los contactos por página, de 1 a 100.
matchstring

all (por defecto) exige que se cumplan todos los filtros. or coincide con cualquier filtro. Consulta Filtrado.

orderstring

Clave de ordenación de esta lista. Consulta las claves de ordenación más abajo.

directionstring

asc o desc.

Claves de filtro

Los contactos de un segmento aceptan las mismas claves de filtro y de orden que Listar contactos, aplicadas además del segmento, por ejemplo email.ends_with=acme.com.

Los filtros de listado son un único nivel de parámetros de consulta key.condition=value. Consulta Filtrado para ver match, order, direction y la lista de condiciones de cada tipo.

Claves de filtro

ClaveTipoCondicionesNotas
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_emptyNombre y apellidos, sin espacios al principio ni al final.
audiencesstringexact, not_exact, contains, not_contains, starts_with, ends_with, empty, not_emptySe compara con el nombre de la primera lista de contactos del contacto por orden alfabético.
created_atdateexact, before, after, empty, not_empty
updated_atdateexact, before, after, empty, not_empty
unsubscribedbooleanexact, not_exact
audience_idstringexact, not_exactSolo exact y not_exact. El valor es un ID de lista de contactos (aud_...).
custom_fields.*stringexact, not_exact, contains, not_contains, starts_with, ends_with, empty, not_emptySustituye * por la clave de un campo personalizado, por ejemplo custom_fields.company.contains=Acme.

Claves de ordenación

Pasa en order una de estas claves y en direction el valor asc o desc: email, first_name, last_name, name, audiences, created_at, updated_at, unsubscribed

Devuelve

dataobject[]
Los contactos de esta página, cada uno con object, id, email, first_name, last_name, custom_fields, unsubscribed, audiences (id, name, subscribed), created_at y updated_at. Los contactos de un segmento con seguimiento también tienen joined_at.
data[].joined_atstring | null
Solo en los segmentos con seguimiento: cuándo empezó la permanencia actual del contacto en el segmento. null hasta que el seguimiento registra al contacto, por ejemplo justo después de que empiece a coincidir, mientras el segmento está en syncing o mientras el seguimiento está en paused.
total_recordsinteger
El número de contactos que coinciden con el segmento, la búsqueda y los filtros.
subscribed_countinteger
Cuántos de ellos pueden recibir campañas: no se han dado de baja de forma global y están suscritos al menos a una lista de contactos.
next_page_urlstring | null
La ruta de la página siguiente, o null en la última página. Lleva page, limit y search; vuelve a añadir tus filtros cuando la sigas.
previous_page_urlstring | null
La ruta de la página anterior, o null en la primera página.

Devuelve 404 si el segmento no existe.

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
}

Obtener el crecimiento de un segmento

Devuelve el historial de un segmento con seguimiento: una fila por día UTC, del más antiguo al más reciente, hasta hoy. Son los datos del gráfico Growth de la página del segmento. Requiere una clave de API con el permiso full.

El historial empieza cuando empieza el seguimiento. Los contactos registrados en el primer recuento tras crear el segmento, o tras reanudar el seguimiento, cuentan como miembros, pero no como entradas.

GET/segments/{id}/growth

Parámetros de ruta

idstringobligatorio
El ID del segmento (seg_…).

Parámetros de consulta

daysintegerpor defecto: 30
El número de días que se devuelven, de 1 a 365, hasta hoy.

Devuelve

objectstring
Siempre segment_growth.
segment_idstring
El ID del segmento.
dataobject[]
Una fila por día.
data[].datestring
El día UTC, YYYY-MM-DD.
data[].members_countinteger | null
Los miembros al final del día, o el último recuento en el caso de hoy. Los días sin un recuento nuevo mantienen el valor anterior, por ejemplo mientras el seguimiento está pausado. null antes de que empezara el seguimiento.
data[].joined_countinteger
Los contactos que entraron en el segmento ese día.
data[].left_countinteger
Los contactos que salieron del segmento ese día.
Código Cuándo
404 El segmento no existe.
422 El segmento no tiene seguimiento.
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 }
  ]
}

Previsualizar un segmento

Comprueba la definición de un segmento sin guardarla: devuelve cuántos contactos coinciden y una muestra de ellos. La definición se valida igual que en Crear un segmento, y una vista previa no cuenta para el límite de segmentos del plan. Requiere una clave de API con el permiso full.

POST/segments/preview

Parámetros del cuerpo

audience_idsstring[]
Los ID de las listas de contactos de las que tomaría sus contactos el segmento. Si está vacío o se omite, se usan todos los contactos.
conditionsobject
Las reglas. Consulta Crear un segmento.
limitintegerpor defecto: 10
El número de contactos de muestra, de 1 a 25.

Devuelve

objectstring
Siempre segment_preview.
audience_idsstring[]
Las listas de contactos de origen, sin duplicados.
conditionsobject
Las reglas tal como se guardarían: un { match, rules } plano se convierte en un grupo y los grupos vacíos se descartan.
contacts_countinteger
Los contactos que coinciden.
subscribed_countinteger
Cuántos de ellos pueden recibir campañas.
contactsobject[]
Los contactos coincidentes más recientes, con la misma forma que en Listar los contactos de un segmento.

Devuelve 422 con errors, con la ruta del campo como clave, si la definición no es vá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 los campos de segmento

Devuelve los campos que pueden usar las reglas de los segmentos en este espacio de trabajo: los campos del contacto, todos los campos personalizados (con el tipo que corresponde a su tipo de campo personalizado), la pertenencia a listas de contactos, los datos de compra y la interacción con las campañas. Requiere una clave de API con el permiso full.

GET/segments/fields

Devuelve

dataobject[]
Un elemento por campo.
data[].keystring
El valor que se usa como field de una regla, por ejemplo email_domain o custom_fields.plan.
data[].labelstring
El nombre visible. En los campos personalizados, el nombre del campo personalizado.
data[].typestring
string, number, date, datetime, boolean, enum, multi, audience, metric, moment, purchase, view, cart, coupon o campaign_activity. Consulta Crear un segmento. Los campos de actividad como purchased aceptan un objeto como valor; consulta Reglas de actividad.
data[].groupstring
contact, custom_fields, audiences, commerce (datos de compra) o engagement (actividad en las campañas).
data[].operatorsstring[]
Los operadores que acepta el campo.
data[].valuesobject[]
Los valores permitidos, como value y label: las opciones de los campos personalizados de selección y de selección múltiple, subscribed y unsubscribed para status, y las listas de contactos del espacio de trabajo para audience. No aparece en los demás 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"]
    }
  ]
}

¿Te ha resultado útil esta página?

Gracias por tu opinión.

Gracias. Leemos todos los mensajes.