Suscriptores

Administre sus contactos de suscriptores, importe listas y rastree la interacción

Administre sus contactos de suscriptores de correo electrónico. Cada suscriptor cuenta con un perfil con seguimiento de interacción, campos personalizados y gestión de estados.

Estados de los suscriptores

Estado	Valor	Descripción
`Active`	0	Suscrito y recibiendo correos electrónicos
`Unsubscribed`	1	Se dio de baja de los correos electrónicos
`Bounced`	2	Rebote permanente registrado
`Complained`	3	Reportó un mensaje como spam
`Pending`	4	Reservado: MailLand no tiene un flujo de doble opt-in, por lo que nada establece este estado jamás

optInMethod y los campos consent* de un suscriptor se registran solo como evidencia: no impulsan ningún flujo de confirmación.

Crear un suscriptor

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

Create subscriber request

{
  "email": "[email protected]",
  "firstName": "John",
  "lastName": "Doe",
  "phone": "+1234567890",
  "company": "Acme Corp",
  "mailingListId": "ddv6ou6kz4wbto",
  "source": "api",
  "birthday": "1990-05-14",
  "customFields": {
    "plan": "enterprise",
    "region": "us-west"
  }
}

Campo	Tipo	Requerido	Descripción
`email`	string	Sí	Dirección de correo electrónico
`firstName`	string	No	Nombre
`lastName`	string	No	Apellido
`phone`	string	No	Número de teléfono
`company`	string	No	Nombre de la empresa
`mailingListId`	string	No	Lista de correo a la que agregar
`source`	string	No	Fuente de suscripción (p. ej., `api`, `form`, `import`)
`birthday`	string	No	`YYYY-MM-DD`. Leído por el disparador de automatización `DateBased`
`customFields`	object	No	Campos personalizados clave-valor

Create a subscriber

curl -X POST https://api.mail.land/v1/marketing/subscribers \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "firstName": "John",
    "lastName": "Doe",
    "mailingListId": "ddv6ou6kz4wbto",
    "source": "api"
  }'

Respuesta

Subscriber response

{
  "id": "exz31qoqlf01sj",
  "email": "[email protected]",
  "firstName": "John",
  "lastName": "Doe",
  "phone": "+1234567890",
  "company": "Acme Corp",
  "status": "active",
  "statusName": "Active",
  "source": "api",
  "mailingListId": "ddv6ou6kz4wbto",
  "mailingListName": "Product Updates",
  "customFields": {
    "plan": "enterprise",
    "region": "us-west"
  },
  "subscribedAt": "2026-02-17T12:00:00Z",
  "unsubscribedAt": null,
  "createdAt": "2026-02-17T12:00:00Z",
  "updatedAt": "2026-02-17T12:00:00Z"
}

Listar suscriptores

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

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 correo o nombre (no por empresa)
`mailingListId`	string	-	Filtrar por lista de correo
`status`	int	-	Filtrar por estado del suscriptor
`sortBy`	string	-	Campo de ordenación
`sortDesc`	bool	false	Ordenar de forma descendente

List subscribers

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

Obtener detalles de un suscriptor

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

Retorna un perfil extendido con métricas de interacción:

Get subscriber details

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

Subscriber detail response

{
  "id": "exz31qoqlf01sj",
  "email": "[email protected]",
  "firstName": "John",
  "lastName": "Doe",
  "phone": "+1234567890",
  "company": "Acme Corp",
  "status": "active",
  "source": "api",
  "mailingListId": "ddv6ou6kz4wbto",
  "mailingListName": "Product Updates",
  "customFields": { "plan": "enterprise" },
  "birthday": "1990-05-14",
  "emailsSent": 50,
  "emailsOpened": 25,
  "emailsClicked": 10,
  "lastEmailSentAt": "2026-02-17T09:30:00Z",
  "lastEmailOpenedAt": "2026-02-16T15:20:00Z",
  "lastEmailClickedAt": "2026-02-15T11:10:00Z",
  "openRate": 50.0,
  "clickRate": 40.0,
  "subscribedAt": "2026-01-15T08:00:00Z",
  "createdAt": "2026-01-15T08:00:00Z",
  "updatedAt": "2026-02-17T12:00:00Z"
}

Actualizar un suscriptor

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

Update subscriber request

{
  "firstName": "Jane",
  "lastName": "Smith",
  "phone": "+1234567890",
  "company": "TechCorp",
  "mailingListId": "ddv6ou6kz4wbto",
  "customFields": { "plan": "pro" },
  "birthday": "1990-05-14",
  "status": "Active"
}

PUT reemplaza todo el perfil, no lo fusiona. firstName, lastName, phone, company y mailingListId se sobrescriben todos con null (o se elimina de la lista) cuando se omiten, no se dejan sin cambios. Omitir mailingListId elimina la membresía de lista del suscriptor. Envíe cada campo que desee conservar, incluido mailingListId. Solo customFields y status permanecen sin cambios cuando se omiten. birthday sigue su propia regla: omitir el campo lo deja sin cambios, enviar "birthday": null lo borra, y un valor YYYY-MM-DD lo establece, una cadena vacía ("") se rechaza con 400. Si el destinatario ya tiene un contacto sin lista, la pertenencia eliminada se conserva solo como historial: ya no aparece en los contactos y se conservan sus bajas, sus registros de consentimiento y su historial de campañas.

Update a subscriber

curl -X PUT https://api.mail.land/v1/marketing/subscribers/exz31qoqlf01sj \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Jane",
    "lastName": "Smith",
    "company": "TechCorp",
    "mailingListId": "ddv6ou6kz4wbto",
    "customFields": { "plan": "pro" },
    "status": "Active"
  }'

Dar de baja a un suscriptor

POST https://api.mail.land/v1/marketing/subscribers/{id}/unsubscribe

Registra una baja limitada a la lista del suscriptor, o a todos los envíos de marketing si el suscriptor no tiene lista, y establece el estado del suscriptor en Unsubscribed con una marca de tiempo unsubscribedAt. El correo transaccional no se ve afectado por esta llamada.

Unsubscribe a subscriber

curl -X POST https://api.mail.land/v1/marketing/subscribers/exz31qoqlf01sj/unsubscribe \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Eliminar un suscriptor

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

Elimina permanentemente al suscriptor y sus datos de interacción. Las bajas y supresiones se conservan, por lo que volver a agregar la misma dirección no la vuelve a suscribir.

Delete a subscriber

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

Importar suscriptores

POST https://api.mail.land/v1/marketing/subscribers/import

Importe suscriptores desde contenido CSV:

Import request

{
  "mailingListId": "ddv6ou6kz4wbto",
  "csvContent": "email,firstName,lastName\n[email protected],John,Doe\n[email protected],Jane,Smith",
  "source": "csv_import",
  "updateExisting": true
}

Campo	Tipo	Requerido	Descripción
`mailingListId`	string	No	Lista de correo de destino
`csvContent`	string	Sí	Datos CSV: vea el aviso de formato abajo, la fila de encabezado no se usa como encabezado

La primera fila se trata como encabezado y se omite, independientemente de su contenido: nunca se lee para mapear las columnas 1–3 a campos. Las columnas son posicionales: la columna 1 siempre es email, la columna 2 siempre firstName, la columna 3 siempre lastName; cualquier otra columna se ignora excepto una encabezada birthday (sin distinguir mayúsculas, en cualquier posición después de la columna 1), que se lee por el nombre de su encabezado, no por su posición. Su valor debe ser YYYY-MM-DD; un valor inválido se reporta por fila en errors y ese contacto igual se importa, solo que sin cumpleaños. Un archivo sin encabezado birthday se comporta exactamente como antes. Los valores se dividen por comas simples, por lo que un valor con una coma entre comillas no es compatible y se dividirá incorrectamente. La respuesta también añade los contadores importedNewMembershipForExistingRecipient, updatedMembership, alreadyMember, suppressed y skippedDuplicateInFile además de lo mostrado abajo.

Import subscribers

curl -X POST https://api.mail.land/v1/marketing/subscribers/import \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "mailingListId": "ddv6ou6kz4wbto",
    "csvContent": "email,firstName,lastName\[email protected],John,Doe\[email protected],Jane,Smith",
    "source": "csv_import",
    "updateExisting": true
  }'

Import response

{
  "imported": 50,
  "updated": 10,
  "skipped": 5,
  "errors": [
    "Invalid email: not-an-email",
    "Could not resolve a recipient identity for: [email protected]"
  ]
}

Los suscriptores importados sí disparan la automatización SubscriberJoins, por cada membresía que el import realmente confirma: igual que una creación individual mediante POST /v1/marketing/subscribers. Un contacto ya en la lista de destino, una repetición dentro del archivo, o una fila perdida por un conflicto (TenantId, Email) no se inscribe. Si la lista de destino tiene una automatización SubscriberJoins activa (o el tenant tiene una que no está ligada a una lista), importar un archivo de contactos nuevos ahora envía esa automatización a cada uno de ellos, dimensione el import en consecuencia. La supresión sigue aplicándose: inscribir nunca evita a un destinatario suprimido.

Exportar suscriptores

GET https://api.mail.land/v1/marketing/subscribers/export

Parámetro	Tipo	Descripción
`mailingListId`	string	Filtrar por lista de correo
`status`	int	Filtrar por estado

Retorna una descarga de archivo CSV con el nombre subscribers_yyyyMMdd_HHmmss.csv.

Export subscribers

curl "https://api.mail.land/v1/marketing/subscribers/export?mailingListId=ddv6ou6kz4wbto" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -o subscribers_export.csv

Estadísticas de suscriptores

GET https://api.mail.land/v1/marketing/subscribers/stats

Parámetro	Tipo	Descripción
`mailingListId`	string	Filtrar por lista de correo

Get subscriber stats

curl "https://api.mail.land/v1/marketing/subscribers/stats?mailingListId=ddv6ou6kz4wbto" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Subscriber stats response

{
  "total": 1500,
  "active": 1200,
  "unsubscribed": 200,
  "bounced": 80,
  "complained": 10,
  "pending": 10
}

Número de suscriptores

GET https://api.mail.land/v1/marketing/subscribers/count

Parámetro	Tipo	Descripción
`mailingListId`	string	Filtrar por lista de correo

Get subscriber count

curl "https://api.mail.land/v1/marketing/subscribers/count?mailingListId=ddv6ou6kz4wbto" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Count response

{
  "count": 1500,
  "mailingListId": "ddv6ou6kz4wbto"
}

Crecimiento de suscriptores

GET https://api.mail.land/v1/marketing/subscribers/growth

Parámetro	Tipo	Predeterminado	Descripción
`days`	int	30	Período de análisis (máx. 90)
`mailingListId`	string	-	Filtrar por lista de correo

Get subscriber growth

curl "https://api.mail.land/v1/marketing/subscribers/growth?days=30&mailingListId=ddv6ou6kz4wbto" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Growth response

{
  "dataPoints": [
    {
      "date": "2026-02-17",
      "newSubscribers": 50,
      "unsubscribes": 5,
      "cumulativeTotal": 1500
    }
  ],
  "totalNew": 500,
  "totalUnsubscribes": 50,
  "netGrowth": 450,
  "currentTotal": 1500
}

Respuestas de error

Estado	Código	Descripción
`400`	`INVALID_EMAIL_FORMAT`	Formato de correo electrónico inválido
`400`	`INVALID_REQUEST`	El correo del suscriptor ya existe
`403`	`FORBIDDEN`	Permisos insuficientes
`404`	`RESOURCE_NOT_FOUND`	Suscriptor no encontrado

Pasos siguientes

Listas: organice sus suscriptores en listas de correo
Segmentos: cree segmentos dinámicos basados en los datos de los suscriptores
Campañas: envíe campañas a sus suscriptores

Suscriptores

Estados de los suscriptoresCopiar enlace de la sección

Crear un suscriptorCopiar enlace de la sección

RespuestaCopiar enlace de la sección

Listar suscriptoresCopiar enlace de la sección

Obtener detalles de un suscriptorCopiar enlace de la sección

Actualizar un suscriptorCopiar enlace de la sección

Dar de baja a un suscriptorCopiar enlace de la sección

Eliminar un suscriptorCopiar enlace de la sección

Importar suscriptoresCopiar enlace de la sección

Exportar suscriptoresCopiar enlace de la sección

Estadísticas de suscriptoresCopiar enlace de la sección

Número de suscriptoresCopiar enlace de la sección

Crecimiento de suscriptoresCopiar enlace de la sección

Respuestas de errorCopiar enlace de la sección

Pasos siguientesCopiar enlace de la sección

En esta página