Módulo 0426 endpoints

Lists `/lists`

Gestión completa de listas, custom fields, importación/exportación y herramientas de limpieza.

Endpoints

26 en total

GET/listsUsuario

Listar listas con estadísticas

Ejemplo

curl -X GET "https://envios.arrobamail.com/v3/api/lists" \
  -H "Authorization: Bearer $TOKEN"

Respuesta 200

{
  "count": 12,
  "list": [
    {
      "id": 45, "encid": "xY7zW2", "nombre": "Clientes VIP",
      "dateCreated": "2025-01-15 08:30:00",
      "s_total": 3500, "s_active": 3200,
      "s_unsus": 150, "s_bkl": 100, "s_notconfirmed": 50
    }
  ]
}

GET/lists/dashboardUsuario

Dashboard analytics de listas

Retorna gráficos y métricas agregadas: crecimiento diario, engagement por lista, distribución de estados.

Ejemplo

curl -X GET "https://envios.arrobamail.com/v3/api/lists/dashboard" \
  -H "Authorization: Bearer $TOKEN"

POST/listsUsuario

Crear nueva lista

Nombre requerido. Verifica límite de listas según plan.

Request body · application/json

Nombre	Tipo	Req.	Descripción
`nombre`	`string`	Sí	Nombre de la lista
`from_email`	`string`	No	Email remitente por defecto
`from_name`	`string`	No	Nombre remitente por defecto
`descripcion`	`string`	No	Descripción de la lista

Ejemplo

curl -X POST "https://envios.arrobamail.com/v3/api/lists" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "nombre": "...",
  "from_email": "...",
  "from_name": "...",
  "descripcion": "..."
}'

Respuesta 201

{ "id": 45, "encid": "xY7zW2" }

Errores

Status	Code	Descripción
400	`name_required`	Nombre obligatorio
400	`max_lists_reached`	Límite de listas alcanzado según el plan

GET/lists/:idUsuario

Detalle completo de lista con stats y custom fields

Parámetros de ruta

Nombre	Descripción
`id`	ID numérico de la lista

Ejemplo

curl -X GET "https://envios.arrobamail.com/v3/api/lists/{ID}" \
  -H "Authorization: Bearer $TOKEN"

PUT/lists/:idUsuario

Actualizar propiedades de lista

Campos editables: nombre, from_email, from_name, descripcion, image_logo.

Parámetros de ruta

Nombre	Descripción
`id`	ID numérico de la lista

Request body · application/json

Nombre	Tipo	Req.	Descripción
`nombre`	`string`	No	Nombre de la lista
`from_email`	`string`	No	Email remitente por defecto
`from_name`	`string`	No	Nombre remitente por defecto
`descripcion`	`string`	No	Descripción
`image_logo`	`string`	No	URL del logo

Ejemplo

curl -X PUT "https://envios.arrobamail.com/v3/api/lists/{ID}" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "nombre": "...",
  "from_email": "...",
  "from_name": "...",
  "descripcion": "...",
  "image_logo": "..."
}'

Respuesta 200

{ "success": true }

DELETE/lists/:idUsuario

Eliminar lista permanentemente

Eliminación permanente e irreversible. Suscriptores y custom fields se eliminan junto con la lista.

Parámetros de ruta

Nombre	Descripción
`id`	ID numérico de la lista

Ejemplo

curl -X DELETE "https://envios.arrobamail.com/v3/api/lists/{ID}" \
  -H "Authorization: Bearer $TOKEN"

Respuesta 200

{ "success": true }

POST/lists/:encid/exportUsuario

Exportar suscriptores a CSV/XLSX

Parámetros de ruta

Nombre	Descripción
`encid`	ID codificado de la lista

Request body · application/json

Nombre	Tipo	Req.	Descripción
`status`	`string`	No	BKL, UNSUS, NOT_CONFIRMED, ACTIVE, SUBSCRIBED

Ejemplo

curl -X POST "https://envios.arrobamail.com/v3/api/lists/{ENCID}/export" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "status": "..."
}'

Respuesta 200

{ "fileName": "export-45.xlsx" }

GET/lists/:id/customFieldsUsuario

Listar campos personalizados de la lista

Parámetros de ruta

Nombre	Descripción
`id`	ID numérico de la lista

Ejemplo

curl -X GET "https://envios.arrobamail.com/v3/api/lists/{ID}/customFields" \
  -H "Authorization: Bearer $TOKEN"

POST/lists/:id/customFieldsUsuario

Crear campo personalizado

Nombre único en la lista. Máximo de campos no excedido.

Parámetros de ruta

Nombre	Descripción
`id`	ID numérico de la lista

Request body · application/json

Nombre	Tipo	Req.	Descripción
`name`	`string`	Sí	Nombre del campo
`type`	`string`	Sí	text, dropdown, radio, date, multiline
`required`	`boolean`	No	Default: false
`internal`	`boolean`	No	Campo interno no visible al suscriptor
`default`	`string`	No	Valor por defecto
`options`	`string[]`	No	Opciones para dropdown/radio

Ejemplo

curl -X POST "https://envios.arrobamail.com/v3/api/lists/{ID}/customFields" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "...",
  "type": "...",
  "required": true,
  "internal": true,
  "default": "...",
  "options": ["..."]
}'

POST/lists/:id/customFields/copyUsuario

Copiar custom fields desde otra lista

Parámetros de ruta

Nombre	Descripción
`id`	ID de la lista destino

Request body · application/json

Nombre	Tipo	Req.	Descripción
`sourceListId`	`number`	Sí	ID de la lista origen

Ejemplo

curl -X POST "https://envios.arrobamail.com/v3/api/lists/{ID}/customFields/copy" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "sourceListId": 0
}'

GET/lists/:id/customField/:fidUsuario

Detalle de campo personalizado

Parámetros de ruta

Nombre	Descripción
`id`	ID numérico de la lista
`fid`	ID del campo personalizado

Ejemplo

curl -X GET "https://envios.arrobamail.com/v3/api/lists/{ID}/customField/{FID}" \
  -H "Authorization: Bearer $TOKEN"

PUT/lists/:id/customField/:fidUsuario

Actualizar campo personalizado

Parámetros de ruta

Nombre	Descripción
`id`	ID numérico de la lista
`fid`	ID del campo personalizado

Request body · application/json

Nombre	Tipo	Req.	Descripción
`name`	`string`	No	Nuevo nombre del campo
`required`	`boolean`	No	Obligatorio
`default`	`string`	No	Valor por defecto
`options`	`string[]`	No	Opciones (dropdown/radio)

Ejemplo

curl -X PUT "https://envios.arrobamail.com/v3/api/lists/{ID}/customField/{FID}" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "...",
  "required": true,
  "default": "...",
  "options": ["..."]
}'

Respuesta 200

{ "success": true }

DELETE/lists/:id/customField/:fidUsuario

Eliminar campo personalizado

Parámetros de ruta

Nombre	Descripción
`id`	ID numérico de la lista
`fid`	ID del campo personalizado

Ejemplo

curl -X DELETE "https://envios.arrobamail.com/v3/api/lists/{ID}/customField/{FID}" \
  -H "Authorization: Bearer $TOKEN"

Respuesta 200

{ "success": true }

GET/lists/:id/subscribersUsuario

Listar suscriptores con paginación

Parámetros de ruta

Nombre	Descripción
`id`	ID numérico de la lista

Query params

Nombre	Tipo	Req.	Default	Descripción
`limit`	`number`	No	`50`	Items por página (máx 100)
`offset`	`number`	No	`0`	Desplazamiento
`q`	`string`	No	`-`	Búsqueda por email o nombre
`status`	`string`	No	`-`	active, unsubscribed, blocked, pending
`sortBy`	`string`	No	`email`	email, nombre, cdate, lastOpen
`sortDir`	`string`	No	`asc`	asc o desc

Ejemplo

curl -X GET "https://envios.arrobamail.com/v3/api/lists/{ID}/subscribers" \
  -H "Authorization: Bearer $TOKEN"

Respuesta 200

{
  "paging": { "total": 3500, "limit": 50, "offset": 0, "pages": 70 },
  "list": [
    {
      "id": 5001, "sid": "sX9kL2",
      "email": "usuario@ejemplo.com",
      "nombre": "Juan Pérez",
      "status": "active",
      "confirmado": true,
      "cdate": "2025-03-15 10:22:00"
    }
  ]
}

POST/lists/:id/subscribersUsuario

Crear suscriptor en la lista

Parámetros de ruta

Nombre	Descripción
`id`	ID numérico de la lista

Request body · application/json

Nombre	Tipo	Req.	Descripción
`email`	`string`	Sí	Email del suscriptor
`nombre`	`string`	No	Nombre
`confirmado`	`boolean`	No	Default: true
`customFields`	`object`	No	{ "fieldId": "value" }

Ejemplo

curl -X POST "https://envios.arrobamail.com/v3/api/lists/{ID}/subscribers" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "...",
  "nombre": "...",
  "confirmado": true,
  "customFields": {}
}'

Errores

Status	Code	Descripción
400	`email_required`	Email obligatorio
400	`invalid_email_format`	Formato de email inválido
409	`email_already_exists`	El email ya existe en la lista

GET/lists/:id/subscribers/:sidUsuario

Detalle de suscriptor con custom fields

Parámetros de ruta

Nombre	Descripción
`id`	ID numérico de la lista
`sid`	ID del suscriptor

Ejemplo

curl -X GET "https://envios.arrobamail.com/v3/api/lists/{ID}/subscribers/{SID}" \
  -H "Authorization: Bearer $TOKEN"

GET/lists/:id/subscribers/:sid/historyUsuario

Historial de actividad del suscriptor

Parámetros de ruta

Nombre	Descripción
`id`	ID numérico de la lista
`sid`	ID del suscriptor

Ejemplo

curl -X GET "https://envios.arrobamail.com/v3/api/lists/{ID}/subscribers/{SID}/history" \
  -H "Authorization: Bearer $TOKEN"

GET/lists/:id/subscribers/:sid/campaignsUsuario

Campañas recibidas por el suscriptor (últimos 90 días)

Parámetros de ruta

Nombre	Descripción
`id`	ID numérico de la lista
`sid`	ID del suscriptor

Ejemplo

curl -X GET "https://envios.arrobamail.com/v3/api/lists/{ID}/subscribers/{SID}/campaigns" \
  -H "Authorization: Bearer $TOKEN"

PUT/lists/:id/subscribers/:sidUsuario

Actualizar datos del suscriptor

Parámetros de ruta

Nombre	Descripción
`id`	ID numérico de la lista
`sid`	ID del suscriptor

Request body · application/json

Nombre	Tipo	Req.	Descripción
`nombre`	`string`	No	Nombre
`customFields`	`object`	No	{ "fieldId": "value" }

Ejemplo

curl -X PUT "https://envios.arrobamail.com/v3/api/lists/{ID}/subscribers/{SID}" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "nombre": "...",
  "customFields": {}
}'

Respuesta 200

{ "success": true }

POST/lists/:id/tools/bulk-unsubscribeUsuario

Desuscribir/eliminar suscriptores masivamente

Operación asíncrona. Progreso en tiempo real vía Socket.io (evento: bulkOperationProgress).

Parámetros de ruta

Nombre	Descripción
`id`	ID numérico de la lista

Request body · application/json

Nombre	Tipo	Req.	Descripción
`emails`	`string[]`	Sí	Array de emails a procesar
`action`	`string`	Sí	"unsubscribe" o "delete"
`scope`	`string`	Sí	"list" (solo esta lista) o "global" (todas las listas)

Ejemplo

curl -X POST "https://envios.arrobamail.com/v3/api/lists/{ID}/tools/bulk-unsubscribe" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "emails": ["..."],
  "action": "...",
  "scope": "..."
}'

Respuesta 200

{ "started": true }

POST/lists/:id/tools/remove-inactiveUsuario

Eliminar suscriptores inactivos

Operación asíncrona con progreso vía Socket.io.

Parámetros de ruta

Nombre	Descripción
`id`	ID numérico de la lista

Request body · application/json

Nombre	Tipo	Req.	Descripción
`days`	`number`	Sí	Días de inactividad para considerar inactivo
`action`	`string`	Sí	"unsubscribe" o "delete"

Ejemplo

curl -X POST "https://envios.arrobamail.com/v3/api/lists/{ID}/tools/remove-inactive" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "days": 0,
  "action": "..."
}'

Respuesta 200

{ "started": true }

GET/lists/:id/tools/preview-inactiveUsuario

Preview de suscriptores inactivos

Parámetros de ruta

Nombre	Descripción
`id`	ID numérico de la lista

Query params

Nombre	Tipo	Req.	Default	Descripción
`days`	`number`	Sí	`-`	Días de inactividad

Ejemplo

curl -X GET "https://envios.arrobamail.com/v3/api/lists/{ID}/tools/preview-inactive" \
  -H "Authorization: Bearer $TOKEN"

Respuesta 200

{
  "totalSubscribers": 3500,
  "inactiveCount": 420,
  "activeCount": 3080,
  "inactivePercentage": 12.0
}

POST/lists/tools/inactive-cleanup/previewUsuario

Preview de limpieza flexible de contactos inactivos

Permite previsualizar contactos inactivos en una o más listas antes de ejecutar la operación.

Request body · application/json

Nombre	Tipo	Req.	Descripción
`listIds`	`array`	Sí	IDs numéricos o codificados de listas
`days`	`number`	Sí	30, 60, 90, 120, 180 o 365
`activity`	`string`	Sí	opens_or_clicks, opens o clicks

Ejemplo

curl -X POST "https://envios.arrobamail.com/v3/api/lists/tools/inactive-cleanup/preview" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "listIds": [],
  "days": 0,
  "activity": "..."
}'

Respuesta 200

{ "summary": { "totalAffected": 85, "totalEligible": 1200 }, "breakdown": [], "sample": [] }

POST/lists/tools/inactive-cleanup/executeUsuario

Ejecutar limpieza flexible de contactos inactivos

Operación asíncrona con progreso vía Socket.io.

Request body · application/json

Nombre	Tipo	Req.	Descripción
`listIds`	`array`	Sí	IDs numéricos o codificados de listas
`days`	`number`	Sí	30, 60, 90, 120, 180 o 365
`activity`	`string`	Sí	opens_or_clicks, opens o clicks
`action`	`string`	Sí	unsubscribe o delete

Ejemplo

curl -X POST "https://envios.arrobamail.com/v3/api/lists/tools/inactive-cleanup/execute" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "listIds": [],
  "days": 0,
  "activity": "...",
  "action": "..."
}'

Respuesta 200

{ "operationId": "abc123", "totalFound": 85, "message": "processing" }

POST/lists/:id/tools/import/analyzeUsuario

Analizar archivo de importación

Content-Type: multipart/form-data. Soporta .xlsx, .xls, .csv, .txt (máx 20MB) o texto plano en campo "text". Retorna formato, headers, preview y fileId.

Parámetros de ruta

Nombre	Descripción
`id`	ID numérico de la lista

Request body · multipart/form-data

Nombre	Tipo	Req.	Descripción
`file`	`file`	No	Archivo .xlsx, .xls, .csv o .txt (máx 20MB)
`text`	`string`	No	Texto plano con emails (alternativa a file)

Ejemplo

curl -X POST "https://envios.arrobamail.com/v3/api/lists/{ID}/tools/import/analyze" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "file": "<archivo>",
  "text": "..."
}'

Errores

Status	Code	Descripción
400	`no_input`	No se envió archivo ni texto

POST/lists/:id/tools/import/executeUsuario

Ejecutar importación de suscriptores

Procesa en background con progreso en tiempo real vía Socket.io (evento: importProgress). Requiere fileId (del análisis previo) o text.

Parámetros de ruta

Nombre	Descripción
`id`	ID numérico de la lista

Request body · application/json

Nombre	Tipo	Req.	Descripción
`fileId`	`string`	No	ID del archivo analizado previamente
`text`	`string`	No	Texto plano alternativo
`columnMapping`	`object`	Sí	Mapeo de columnas { columnIndex: fieldName }

Ejemplo

curl -X POST "https://envios.arrobamail.com/v3/api/lists/{ID}/tools/import/execute" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "fileId": "...",
  "text": "...",
  "columnMapping": {}
}'

Respuesta 200

{ "started": true }

Errores

Status	Code	Descripción
400	`no_input`	No se enviaron datos
400	`no_email_column`	Columna email no mapeada
400	`file_not_found`	FileId no existe o expiró

Empezá con arrobaMail
en menos de 5 minutos.

Plan Gratuito, generaciones de IA incluidas, sin tarjeta de crédito y soporte real en español.

Probar gratis ahora

Lists /lists

Listar listas con estadísticas

Dashboard analytics de listas

Crear nueva lista

Detalle completo de lista con stats y custom fields

Actualizar propiedades de lista

Eliminar lista permanentemente

Exportar suscriptores a CSV/XLSX

Listar campos personalizados de la lista

Crear campo personalizado

Copiar custom fields desde otra lista

Detalle de campo personalizado

Actualizar campo personalizado

Eliminar campo personalizado

Listar suscriptores con paginación

Crear suscriptor en la lista

Detalle de suscriptor con custom fields

Historial de actividad del suscriptor

Campañas recibidas por el suscriptor (últimos 90 días)

Actualizar datos del suscriptor

Desuscribir/eliminar suscriptores masivamente

Eliminar suscriptores inactivos

Preview de suscriptores inactivos

Preview de limpieza flexible de contactos inactivos

Ejecutar limpieza flexible de contactos inactivos

Analizar archivo de importación

Ejecutar importación de suscriptores

Empezá con arrobaMailen menos de 5 minutos.

Lists `/lists`

Empezá con arrobaMail
en menos de 5 minutos.