Segmentos

Cree segmentos dinámicos basados en atributos y comportamiento de los suscriptores

Los segmentos son grupos dinámicos de suscriptores definidos por condiciones. A diferencia de las listas estáticas, los segmentos se actualizan automáticamente a medida que cambian los datos de los suscriptores. Utilice segmentos para dirigir campañas a audiencias específicas según atributos, participación y comportamiento.

Tipos de coincidencia

Tipo de coincidencia	Valor	Descripción
`All`	0	Todas las condiciones deben coincidir (lógica AND)
`Any`	1	Cualquier condición puede coincidir (lógica OR)

Crear un segmento

POST https://api.mail.land/v1/marketing/segments

Create segment request

{
  "name": "Active Engaged Users",
  "description": "Users who opened or clicked in last 30 days",
  "matchType": "All",
  "conditions": [
    {
      "field": "lastemailopenedat",
      "operator": "inlast",
      "value": "30"
    },
    {
      "field": "status",
      "operator": "equals",
      "value": "Active"
    }
  ]
}

Campo	Tipo	Requerido	Descripción
`name`	string	Sí	Nombre del segmento (único por espacio de trabajo)
`description`	string	No	Descripción del segmento
`matchType`	string	No	`All` (predeterminado) o `Any`
`conditions`	array	Sí	Al menos una condición

Create a segment

curl -X POST https://api.mail.land/v1/marketing/segments \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Active Engaged Users",
    "matchType": "All",
    "conditions": [
      { "field": "lastemailopenedat", "operator": "inlast", "value": "30" },
      { "field": "status", "operator": "equals", "value": "Active" }
    ]
  }'

Respuesta

Segment response

{
  "id": "0qe306asbapwvd",
  "name": "Active Engaged Users",
  "description": "Users who opened or clicked in last 30 days",
  "matchType": "all",
  "matchTypeName": "All",
  "conditionsCount": 2,
  "subscriberCount": 450,
  "createdAt": "2026-02-17T12:00:00Z",
  "updatedAt": "2026-02-17T12:00:00Z"
}

Las respuestas devuelven matchType en minúsculas ("all" / "any") aunque la solicitud de creación/actualización acepte "All"/"Any".

Los campos de condición basados en aperturas/clics (emailsopened, lastemailopenedat, etc.) incluyen actividad de máquinas, la precarga de Apple Mail Privacy Protection y los escáneres de enlaces de seguridad, que no se filtra hoy.

También existe un endpoint no documentado GET /{id}/preview, que devuelve una muestra de suscriptores que actualmente coinciden con las condiciones del segmento.

Campos de condición

Campos de texto

Campos: email, firstname, lastname, company, source, phone

Operador	Descripción	Valor requerido
`equals`	Coincidencia exacta	Sí
`notequals`	No igual	Sí
`contains`	Contiene subcadena	Sí
`notcontains`	No contiene	Sí
`startswith`	Comienza con	Sí
`endswith`	Termina con	Sí
`isempty`	El campo está vacío	No
`isnotempty`	El campo no está vacío	No

Campos numéricos

Campos: emailssent, emailsopened, emailsclicked

Operador	Descripción	Valor requerido	Valor2 requerido
`equals`	Igual a	Sí	No
`notequals`	No igual	Sí	No
`greaterthan`	Mayor que	Sí	No
`greaterthanorequal`	Mayor o igual	Sí	No
`lessthan`	Menor que	Sí	No
`lessthanorequal`	Menor o igual	Sí	No
`between`	Entre dos valores	Sí	Sí

Campos de fecha

Campos: createdat, subscribedat, lastemailsentat, lastemailopenedat, lastemailclickedat

Operador	Descripción	Valor requerido
`equals`	En fecha específica	Sí (fecha ISO)
`before`	Antes de la fecha	Sí (fecha ISO)
`after`	Después de la fecha	Sí (fecha ISO)
`onorbefore`	En o antes	Sí (fecha ISO)
`onorafter`	En o después	Sí (fecha ISO)
`between`	Entre fechas	Sí (value + value2)
`inlast`	En los últimos N días	Sí (días entero)
`isnull`	Fecha no establecida	No
`isnotnull`	Fecha establecida	No

Campos enum

Campo: status

Operador	Descripción	Valores
`equals`	Igual al estado	`Active`, `Unsubscribed`, `Bounced`, `Complained`
`notequals`	No igual a	Mismos valores

Ejemplos de condiciones

Email domain filter

{ "field": "email", "operator": "contains", "value": "example.com" }

High engagement filter

{ "field": "emailssent", "operator": "between", "value": "10", "value2": "50" }

Recent clickers

{ "field": "lastemailclickedat", "operator": "inlast", "value": "7" }

Missing first name

{ "field": "firstname", "operator": "isempty" }

Obtener metadatos del segmento

Recupere todos los campos, operadores y valores enum disponibles para construir condiciones de segmento:

GET https://api.mail.land/v1/marketing/segments/metadata/fields

Get segment metadata

curl https://api.mail.land/v1/marketing/segments/metadata/fields \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Metadata response

{
  "fields": [
    {
      "name": "email",
      "label": "Email",
      "type": "string",
      "operators": ["equals", "notequals", "contains", "notcontains", "startswith", "endswith", "isempty", "isnotempty"],
      "enumValues": null
    },
    {
      "name": "status",
      "label": "Status",
      "type": "enum",
      "operators": ["equals", "notequals"],
      "enumValues": ["Active", "Unsubscribed", "Bounced", "Complained"]
    }
  ]
}

Listar segmentos

GET https://api.mail.land/v1/marketing/segments

Parámetro	Tipo	Predeterminado	Descripción
`cursor`	string	-	Cursor opaco del `nextCursor` de la página anterior. Omitir para la primera página.
`limit`	int	20	Elementos por página
`search`	string	-	Buscar por nombre o descripción
`sortBy`	string	-	Campo de ordenamiento
`sortDesc`	bool	false	Ordenar descendente

List segments

curl "https://api.mail.land/v1/marketing/segments?limit=20" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Obtener detalles del segmento

GET https://api.mail.land/v1/marketing/segments/{id}

Devuelve el segmento completo con sus condiciones:

Get segment details

curl https://api.mail.land/v1/marketing/segments/0qe306asbapwvd \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Segment detail response

{
  "id": "0qe306asbapwvd",
  "name": "Active Engaged Users",
  "description": "Users who engaged in last 30 days",
  "matchType": "all",
  "matchTypeName": "All",
  "conditionsCount": 2,
  "subscriberCount": 450,
  "conditions": [
    {
      "field": "lastemailopenedat",
      "operator": "inlast",
      "value": "30",
      "value2": null
    },
    {
      "field": "status",
      "operator": "equals",
      "value": "Active",
      "value2": null
    }
  ],
  "cachedCount": 450,
  "cachedAt": "2026-02-17T10:00:00Z",
  "createdAt": "2026-01-10T08:00:00Z",
  "updatedAt": "2026-02-17T10:00:00Z"
}

Previsualizar condiciones

Previsualice el resultado de las condiciones antes de crear un segmento. La evaluación de segmentos siempre se restringe a suscriptores con estado Active, por lo que una condición como status notequals Active no coincide con nadie.

POST https://api.mail.land/v1/marketing/segments/preview

Preview request

{
  "conditions": [
    { "field": "lastemailopenedat", "operator": "inlast", "value": "30" }
  ],
  "matchType": "All"
}

Preview segment conditions

curl -X POST https://api.mail.land/v1/marketing/segments/preview \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "conditions": [
      { "field": "lastemailopenedat", "operator": "inlast", "value": "30" }
    ],
    "matchType": "All"
  }'

Preview response

{
  "count": 450,
  "sampleEmails": [
    "[email protected]",
    "[email protected]",
    "[email protected]"
  ]
}

Obtener recuento del segmento

GET https://api.mail.land/v1/marketing/segments/{id}/count

Get segment count

curl https://api.mail.land/v1/marketing/segments/0qe306asbapwvd/count \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Count response

{
  "segmentId": "0qe306asbapwvd",
  "count": 450
}

Actualizar caché del segmento

Forzar un recuento de suscriptores coincidentes:

POST https://api.mail.land/v1/marketing/segments/{id}/refresh

Refresh segment cache

curl -X POST https://api.mail.land/v1/marketing/segments/0qe306asbapwvd/refresh \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Refresh response

{
  "segmentId": "0qe306asbapwvd",
  "count": 460,
  "refreshedAt": "2026-02-17T12:30:00Z"
}

Duplicar un segmento

POST https://api.mail.land/v1/marketing/segments/{id}/duplicate?name=Copy%20of%20Segment

Crea un nuevo segmento con condiciones clonadas. El parámetro name es opcional.

Duplicate a segment

curl -X POST "https://api.mail.land/v1/marketing/segments/0qe306asbapwvd/duplicate?name=Copy%20of%20Segment" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Actualizar un segmento

PUT https://api.mail.land/v1/marketing/segments/{id}

El cuerpo de la solicitud coincide con la solicitud de creación. Actualizar un segmento actualiza automáticamente su recuento en caché.

Update a segment

curl -X PUT https://api.mail.land/v1/marketing/segments/0qe306asbapwvd \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Active Engaged Users (Updated)",
    "matchType": "All",
    "conditions": [
      { "field": "lastemailopenedat", "operator": "inlast", "value": "14" },
      { "field": "status", "operator": "equals", "value": "Active" }
    ]
  }'

Eliminar un segmento

DELETE https://api.mail.land/v1/marketing/segments/{id}

Eliminar un segmento lo desvincula de cualquier campaña en estado Draft o Scheduled que lo tenga como objetivo (el segmentId de la campaña queda en null), lo que la deja sin audiencia: al enviarla se obtiene 422 o no se entrega a nadie. Una campaña que ya está Sending no se ve afectada, porque sus destinatarios ya fueron resueltos.

Delete a segment

curl -X DELETE https://api.mail.land/v1/marketing/segments/0qe306asbapwvd \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Respuestas de error

Estado	Código	Descripción
`400`	`VALIDATION_FAILED`	Nombre o condiciones inválidos
`400`	`INVALID_REQUEST`	El nombre del segmento ya existe
`403`	`FORBIDDEN`	Permisos insuficientes
`404`	`RESOURCE_NOT_FOUND`	Segmento no encontrado

Próximos pasos

Campañas: dirigir campañas con segmentos
Automatizaciones: las automatizaciones no se activan actualmente por membresía de segmento
Suscriptores: gestionar los contactos en sus segmentos

Segmentos

Tipos de coincidenciaCopiar enlace de la sección

Crear un segmentoCopiar enlace de la sección

RespuestaCopiar enlace de la sección

Campos de condiciónCopiar enlace de la sección

Campos de textoCopiar enlace de la sección

Campos numéricosCopiar enlace de la sección

Campos de fechaCopiar enlace de la sección

Campos enumCopiar enlace de la sección

Ejemplos de condicionesCopiar enlace de la sección

Obtener metadatos del segmentoCopiar enlace de la sección

Listar segmentosCopiar enlace de la sección

Obtener detalles del segmentoCopiar enlace de la sección

Previsualizar condicionesCopiar enlace de la sección

Obtener recuento del segmentoCopiar enlace de la sección

Actualizar caché del segmentoCopiar enlace de la sección

Duplicar un segmentoCopiar enlace de la sección

Actualizar un segmentoCopiar enlace de la sección

Eliminar un segmentoCopiar enlace de la sección

Respuestas de errorCopiar enlace de la sección

Próximos pasosCopiar enlace de la sección

En esta página