Segmentos

Un segmento es un grupo con nombre de contactos al que puedes apuntar campañas o usar para iniciar flujos de trabajo. Los segmentos vienen en dos variantes: Dinámico y Estático.

Dinámico vs. Estático

Recurre a los segmentos dinámicos cuando la membresía debe seguir el comportamiento ("suscriptores del plan Pro que abrieron algún correo en los últimos 14 días"). Recurre a los segmentos estáticos cuando la lista se cura a mano — testers beta, asistentes a un evento o contactos importados desde otro sistema.

Filtrar un segmento dinámico

La membresía dinámica depende de un filtro: un conjunto de condiciones que se evalúa contra cada contacto. Las condiciones pueden hacer referencia a:

• Los campos integrados email, subscribed, createdAt y updatedAt.
• Cualquier campo personalizado que hayas guardado en los contactos (todo bajo data.*).
• Eventos que hayas registrado mediante /v1/track (event.signed_up, event.purchased, etc.).
• Señales de interacción como email.opened, email.clicked y email.bounced.
• Si el contacto pertenece a otro segmento.

Las condiciones se combinan con AND / OR y pueden anidarse en grupos, de modo que audiencias como "usuarios Pro suscritos y (abrieron o hicieron clic en un correo en los últimos 14 días)" son expresables.

Cada campo, operador y tipo de valor disponible — con ejemplos resueltos — está documentado en la referencia de filtros de segmento.

Segmentos estáticos

Un segmento estático es una lista que mantienes tú mismo. Nada entra ni sale de ella automáticamente; su membresía es exactamente lo que hayas puesto en ella.

Creación

En el panel, abre Segmentos, pulsa Crear segmento y elige Estático. Si quieres, añade miembros iniciales de inmediato mediante la búsqueda de contactos.

Añadir y quitar miembros

Dentro de un segmento estático, la búsqueda Agregar miembros encuentra contactos para incluir. Solo muestra contactos que ya existen en el proyecto — así que no hay forma de añadir uno inexistente por error — y los miembros que ya están en el segmento aparecen en gris.

Vía la API:

• POST /segments/:id/members — añade contactos por correo. Body: { emails: string[], createMissing?: boolean, subscribed?: boolean }. Poner createMissing: true crea al instante cualquier contacto faltante (suscrito por defecto, salvo que se pase subscribed: false). La respuesta resume { added, created, notFound }.
• DELETE /segments/:id/members — quita contactos por correo. Body: { emails: string[] }. Responde con { removed }.

Estos dos endpoints funcionan exclusivamente con segmentos estáticos — apuntarlos a uno dinámico produce 400.

Los cambios de membresía hechos vía API surten efecto de inmediato, pero nunca emiten eventos entry/exit; esos existen solo para segmentos dinámicos con el seguimiento activado.

Registrar cambios de membresía

Un segmento dinámico puede activar Registrar cambios de membresía. Con esto activado, Bitelio emite un evento cada vez que un contacto entra o sale:

• segment.<slug>.entry — el contacto entró
• segment.<slug>.exit — el contacto salió

Bitelio construye <slug> a partir del nombre del segmento: todo en minúsculas, sin acentos ni puntuación, los espacios se convierten en guiones y las secuencias de guiones se colapsan en uno solo. Así, "VIP Customers" produce segment.vip-customers.entry. Elige nombres cuyos slugs no vayan a necesitar cambiar — renombrar el segmento implica un nuevo nombre de evento.

Estos eventos son una forma natural de impulsar flujos de trabajo: dar la bienvenida a los contactos que entran en un segmento "Trial users", o intentar recuperar a los que salen de "Active users". El formato del payload está documentado en Webhooks.

Cómo funciona el seguimiento

Crear un segmento dinámico o editar su filtro actualiza el recuento de miembros de inmediato. A partir de ahí, la membresía se recalcula en segundo plano a intervalos regulares: Bitelio compara las coincidencias actuales con el último conjunto conocido, registra quién entró y quién salió, y dispara los eventos correspondientes.

Ese intervalo en segundo plano significa que el memberCount del panel puede ir unos minutos por detrás de la realidad. Cuando necesites una cifra actualizada, o quieras que los eventos entry / exit se disparen sin esperar:

• POST /segments/:id/refresh — solo recuenta (económico, no emite nada).
• POST /segments/:id/compute — ejecuta un recálculo completo de la membresía, liberando cualquier evento de entrada/salida pendiente.

Uso de segmentos

Los segmentos se conectan en dos lugares:

• Como audiencias de campañas en campañas de correo (apunta la audiencia de la campaña al segmento)
• Como disparadores de flujos de trabajo en la automatización de marketing (escucha el evento segment.<slug>.entry)

Notas de rendimiento

• Las comparaciones de fechas en campos data.* funcionan ordenando cadenas ISO 8601. Para usar within / olderThan sobre una fecha personalizada, guárdala como una cadena ISO 8601 (2026-05-06T12:00:00Z), no como un timestamp Unix.
• Encadenar muchos segmentos dinámicos sin seguimiento unos dentro de otros hace que la evaluación sea costosa. Cuando un segmento es referenciado por otros, activa Registrar cambios de membresía para él — así su lista de miembros se lee directamente en lugar de recalcularse en cada evaluación.
• memberCount es una caché que puede ir unos minutos por detrás. Trátalo como una estimación, y llama a POST /segments/:id/refresh cuando necesites una cifra exacta.

Eliminar un segmento

Si un segmento respalda una campaña activa (en DRAFT, SCHEDULED o SENDING), eliminarlo falla con 409 Conflict. Cancela esa campaña o cambia su audiencia antes de eliminar el segmento.

Referencia de la API

Todos los endpoints de segmentos — listar, obtener, crear, actualizar, eliminar, listar miembros, añadir/quitar miembros estáticos, refrescar el recuento y calcular la membresía — están catalogados en el resumen de la API.

Qué sigue