Module 0426 endpoints

Lists `/lists`

Full management of lists, custom fields, import/export, and cleanup tools.

Endpoints

26 total

GET/listsUser

List lists with statistics

Example

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

Response 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/dashboardUser

Lists analytics dashboard

Returns charts and aggregate metrics: daily growth, engagement per list, status distribution.

Example

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

POST/listsUser

Create new list

Name required. Checks the list limit for the plan.

Request body · application/json

Name	Type	Req.	Description
`nombre`	`string`	Yes	List name
`from_email`	`string`	No	Default sender email
`from_name`	`string`	No	Default sender name
`descripcion`	`string`	No	List description

Example

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": "..."
}'

Response 201

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

Errors

Status	Code	Description
400	`name_required`	Name required
400	`max_lists_reached`	List limit reached for your plan

GET/lists/:idUser

Full list detail with stats and custom fields

Path parameters

Name	Description
`id`	Numeric list ID

Example

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

PUT/lists/:idUser

Update list properties

Editable fields: nombre, from_email, from_name, descripcion, image_logo.

Path parameters

Name	Description
`id`	Numeric list ID

Request body · application/json

Name	Type	Req.	Description
`nombre`	`string`	No	List name
`from_email`	`string`	No	Default sender email
`from_name`	`string`	No	Default sender name
`descripcion`	`string`	No	Description
`image_logo`	`string`	No	Logo URL

Example

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": "..."
}'

Response 200

{ "success": true }

DELETE/lists/:idUser

Permanently delete list

Permanent, irreversible deletion. Subscribers and custom fields are deleted along with the list.

Path parameters

Name	Description
`id`	Numeric list ID

Example

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

Response 200

{ "success": true }

POST/lists/:encid/exportUser

Export subscribers to CSV/XLSX

Path parameters

Name	Description
`encid`	Encoded list ID

Request body · application/json

Name	Type	Req.	Description
`status`	`string`	No	BKL, UNSUS, NOT_CONFIRMED, ACTIVE, SUBSCRIBED

Example

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

Response 200

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

GET/lists/:id/customFieldsUser

List the list's custom fields

Path parameters

Name	Description
`id`	Numeric list ID

Example

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

POST/lists/:id/customFieldsUser

Create custom field

Name unique within the list. Field limit not exceeded.

Path parameters

Name	Description
`id`	Numeric list ID

Request body · application/json

Name	Type	Req.	Description
`name`	`string`	Yes	Field name
`type`	`string`	Yes	text, dropdown, radio, date, multiline
`required`	`boolean`	No	Default: false
`internal`	`boolean`	No	Internal field, not visible to the subscriber
`default`	`string`	No	Default value
`options`	`string[]`	No	Options for dropdown/radio

Example

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/copyUser

Copy custom fields from another list

Path parameters

Name	Description
`id`	Target list ID

Request body · application/json

Name	Type	Req.	Description
`sourceListId`	`number`	Yes	Source list ID

Example

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/:fidUser

Custom field detail

Path parameters

Name	Description
`id`	Numeric list ID
`fid`	Custom field ID

Example

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

PUT/lists/:id/customField/:fidUser

Update custom field

Path parameters

Name	Description
`id`	Numeric list ID
`fid`	Custom field ID

Request body · application/json

Name	Type	Req.	Description
`name`	`string`	No	New field name
`required`	`boolean`	No	Required
`default`	`string`	No	Default value
`options`	`string[]`	No	Options (dropdown/radio)

Example

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": ["..."]
}'

Response 200

{ "success": true }

DELETE/lists/:id/customField/:fidUser

Delete custom field

Path parameters

Name	Description
`id`	Numeric list ID
`fid`	Custom field ID

Example

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

Response 200

{ "success": true }

GET/lists/:id/subscribersUser

List subscribers with pagination

Path parameters

Name	Description
`id`	Numeric list ID

Query params

Name	Type	Req.	Default	Description
`limit`	`number`	No	`50`	Items per page (max 100)
`offset`	`number`	No	`0`	Offset
`q`	`string`	No	`-`	Search by email or name
`status`	`string`	No	`-`	active, unsubscribed, blocked, pending
`sortBy`	`string`	No	`email`	email, nombre, cdate, lastOpen
`sortDir`	`string`	No	`asc`	asc or desc

Example

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

Response 200

{
  "paging": { "total": 3500, "limit": 50, "offset": 0, "pages": 70 },
  "list": [
    {
      "id": 5001, "sid": "sX9kL2",
      "email": "[email protected]",
      "nombre": "John Doe",
      "status": "active",
      "confirmado": true,
      "cdate": "2025-03-15 10:22:00"
    }
  ]
}

POST/lists/:id/subscribersUser

Create subscriber in the list

Path parameters

Name	Description
`id`	Numeric list ID

Request body · application/json

Name	Type	Req.	Description
`email`	`string`	Yes	Subscriber email
`nombre`	`string`	No	Name
`confirmado`	`boolean`	No	Default: true
`customFields`	`object`	No	{ "fieldId": "value" }

Example

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": {}
}'

Errors

Status	Code	Description
400	`email_required`	Email required
400	`invalid_email_format`	Invalid email format
409	`email_already_exists`	The email already exists in the list

GET/lists/:id/subscribers/:sidUser

Subscriber detail with custom fields

Path parameters

Name	Description
`id`	Numeric list ID
`sid`	Subscriber ID

Example

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

GET/lists/:id/subscribers/:sid/historyUser

Subscriber activity history

Path parameters

Name	Description
`id`	Numeric list ID
`sid`	Subscriber ID

Example

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

GET/lists/:id/subscribers/:sid/campaignsUser

Campaigns received by the subscriber (last 90 days)

Path parameters

Name	Description
`id`	Numeric list ID
`sid`	Subscriber ID

Example

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

PUT/lists/:id/subscribers/:sidUser

Update subscriber data

Path parameters

Name	Description
`id`	Numeric list ID
`sid`	Subscriber ID

Request body · application/json

Name	Type	Req.	Description
`nombre`	`string`	No	Name
`customFields`	`object`	No	{ "fieldId": "value" }

Example

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": {}
}'

Response 200

{ "success": true }

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

Bulk unsubscribe/delete subscribers

Asynchronous operation. Real-time progress via Socket.io (event: bulkOperationProgress).

Path parameters

Name	Description
`id`	Numeric list ID

Request body · application/json

Name	Type	Req.	Description
`emails`	`string[]`	Yes	Array of emails to process
`action`	`string`	Yes	"unsubscribe" or "delete"
`scope`	`string`	Yes	"list" (this list only) or "global" (all lists)

Example

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": "..."
}'

Response 200

{ "started": true }

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

Delete inactive subscribers

Asynchronous operation with progress via Socket.io.

Path parameters

Name	Description
`id`	Numeric list ID

Request body · application/json

Name	Type	Req.	Description
`days`	`number`	Yes	Days of inactivity to consider inactive
`action`	`string`	Yes	"unsubscribe" or "delete"

Example

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": "..."
}'

Response 200

{ "started": true }

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

Preview of inactive subscribers

Path parameters

Name	Description
`id`	Numeric list ID

Query params

Name	Type	Req.	Default	Description
`days`	`number`	Yes	`-`	Days of inactivity

Example

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

Response 200

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

POST/lists/tools/inactive-cleanup/previewUser

Preview flexible cleanup of inactive contacts

Lets you preview inactive contacts in one or more lists before running the operation.

Request body · application/json

Name	Type	Req.	Description
`listIds`	`array`	Yes	Numeric or encoded list IDs
`days`	`number`	Yes	30, 60, 90, 120, 180, or 365
`activity`	`string`	Yes	opens_or_clicks, opens or clicks

Example

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": "..."
}'

Response 200

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

POST/lists/tools/inactive-cleanup/executeUser

Run flexible cleanup of inactive contacts

Asynchronous operation with progress via Socket.io.

Request body · application/json

Name	Type	Req.	Description
`listIds`	`array`	Yes	Numeric or encoded list IDs
`days`	`number`	Yes	30, 60, 90, 120, 180, or 365
`activity`	`string`	Yes	opens_or_clicks, opens or clicks
`action`	`string`	Yes	unsubscribe or delete

Example

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": "..."
}'

Response 200

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

POST/lists/:id/tools/import/analyzeUser

Analyze import file

Content-Type: multipart/form-data. Supports .xlsx, .xls, .csv, .txt (max 20MB) or plain text in the "text" field. Returns format, headers, preview, and fileId.

Path parameters

Name	Description
`id`	Numeric list ID

Request body · multipart/form-data

Name	Type	Req.	Description
`file`	`file`	No	File .xlsx, .xls, .csv, or .txt (max 20MB)
`text`	`string`	No	Plain text with emails (alternative to file)

Example

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": "..."
}'

Errors

Status	Code	Description
400	`no_input`	No file or text was sent

POST/lists/:id/tools/import/executeUser

Run subscriber import

Processes in the background with real-time progress via Socket.io (event: importProgress). Requires fileId (from the prior analysis) or text.

Path parameters

Name	Description
`id`	Numeric list ID

Request body · application/json

Name	Type	Req.	Description
`fileId`	`string`	No	ID of the previously analyzed file
`text`	`string`	No	Alternative plain text
`columnMapping`	`object`	Yes	Column mapping { columnIndex: fieldName }

Example

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": {}
}'

Response 200

{ "started": true }

Errors

Status	Code	Description
400	`no_input`	No data was sent
400	`no_email_column`	Email column not mapped
400	`file_not_found`	FileId doesn't exist or expired

Get started with arrobaMail
in under 5 minutes.

Free plan, AI generations included, no credit card required — and real support from a real team.

Try it free now

Lists /lists

List lists with statistics

Lists analytics dashboard

Create new list

Full list detail with stats and custom fields

Update list properties

Permanently delete list

Export subscribers to CSV/XLSX

List the list's custom fields

Create custom field

Copy custom fields from another list

Custom field detail

Update custom field

Delete custom field

List subscribers with pagination

Create subscriber in the list

Subscriber detail with custom fields

Subscriber activity history

Campaigns received by the subscriber (last 90 days)

Update subscriber data

Bulk unsubscribe/delete subscribers

Delete inactive subscribers

Preview of inactive subscribers

Preview flexible cleanup of inactive contacts

Run flexible cleanup of inactive contacts

Analyze import file

Run subscriber import

Get started with arrobaMailin under 5 minutes.

Lists `/lists`

Get started with arrobaMail
in under 5 minutes.