Listas

Las listas de correo le permiten organizar suscriptores en grupos para campañas dirigidas. Cada registro de suscriptor pertenece a una lista, pero la misma dirección de correo puede tener registros separados en varias listas, y las campañas pueden apuntar a una lista específica o a un segmento dentro de ella.

Crear una lista

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

Create list request

{
  "name": "Product Updates",
  "description": "Subscribers interested in product announcements"
}

Campo	Tipo	Requerido	Descripción
`name`	string	Sí	Nombre de la lista (debe ser único por espacio de trabajo)
`description`	string	No	Descripción de la lista

Create a mailing list

curl -X POST https://api.mail.land/v1/marketing/lists \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{ "name": "Product Updates", "description": "Product announcements" }'

Respuesta

List response

{
  "id": "vtmlew96u277jq",
  "name": "Product Updates",
  "description": "Product announcements",
  "isActive": true,
  "subscriberCount": 0,
  "createdAt": "2026-02-17T12:00:00Z",
  "updatedAt": "2026-02-17T12:00:00Z"
}

Listar todas las listas de correo

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

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
`isActive`	bool	-	Filtrar por estado activo
`sortBy`	string	-	Campo de ordenamiento
`sortDesc`	bool	false	Orden descendente

List all mailing lists

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

List response

{
  "items": [
    {
      "id": "vtmlew96u277jq",
      "name": "Product Updates",
      "description": "Product announcements",
      "isActive": true,
      "subscriberCount": 2500,
      "createdAt": "2026-01-10T08:00:00Z",
      "updatedAt": "2026-02-17T12:00:00Z"
    }
  ],
  "nextCursor": "eyJ2IjoxLCJzIjoiY3JlYXRlZGF0OmRlc2MiLCJrIjoi...",
  "hasMore": true
}

Obtener detalles de una lista

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

Devuelve detalles extendidos incluyendo el desglose de suscriptores:

Get list details

curl https://api.mail.land/v1/marketing/lists/vtmlew96u277jq \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

List detail response

{
  "id": "vtmlew96u277jq",
  "name": "Product Updates",
  "description": "Product announcements",
  "isActive": true,
  "subscriberCount": 2500,
  "activeSubscribers": 2300,
  "unsubscribedCount": 150,
  "bouncedCount": 50,
  "createdAt": "2026-01-10T08:00:00Z",
  "updatedAt": "2026-02-17T12:00:00Z"
}

Actualizar una lista

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

Update list request

{
  "name": "Product Announcements",
  "description": "Updated description",
  "isActive": true
}

Campo	Tipo	Requerido	Descripción
`name`	string	Sí	Nombre de la lista (debe ser único)
`description`	string	No	Descripción de la lista
`isActive`	bool	No	Estado activo (predeterminado: `true`)

isActive es solo una etiqueta: establecerlo en false no bloquea el envío. Nada en el código de campañas o del worker lee este campo para impedir que una campaña apunte a esta lista.

Update a mailing list

curl -X PUT https://api.mail.land/v1/marketing/lists/vtmlew96u277jq \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Product Announcements",
    "description": "Updated description",
    "isActive": true
  }'

Eliminar una lista

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

Elimina la lista de correo. Los suscriptores de esta lista no se eliminan, pero su mailingListId es borrado (una clave foránea SetNull). Las bajas específicas de la lista se conservan cuando se elimina una lista.

Si un suscriptor de esta lista ya tiene un contacto sin lista (por ejemplo, porque estaba en otra lista eliminada antes), ese contacto se conserva y su membresía de esta lista solo se guarda como historial: deja de aparecer en los contactos y ninguna campaña ni automatización la usa como destino. Se conservan sus bajas, registros de consentimiento e historial de campañas.

Delete a mailing list

curl -X DELETE https://api.mail.land/v1/marketing/lists/vtmlew96u277jq \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Respuestas de error

Estado	Código	Descripción
`400`	`VALIDATION_FAILED`	El nombre es requerido
`400`	`INVALID_REQUEST`	Ya existe una lista de correo con este nombre
`403`	`FORBIDDEN`	Permisos insuficientes
`404`	`RESOURCE_NOT_FOUND`	Lista de correo no encontrada

Próximos pasos

Suscriptores: agregue suscriptores a sus listas
Segmentos: cree segmentos dinámicos dentro de las listas
Campañas: envíe campañas a sus listas

Listas

Crear una listaCopiar enlace de la sección

RespuestaCopiar enlace de la sección

Listar todas las listas de correoCopiar enlace de la sección

Obtener detalles de una listaCopiar enlace de la sección

Actualizar una listaCopiar enlace de la sección

Eliminar una listaCopiar 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