Módulo 0426 endpoints

Lists `/lists`

Gestão completa de listas, campos personalizados, importação/exportação e ferramentas de limpeza.

Endpoints

26 no total

GET/listsUsuário

Listar listas com estatísticas

Exemplo

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

Resposta 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/dashboardUsuário

Dashboard de análise de listas

Retorna gráficos e métricas agregadas: crescimento diário, engajamento por lista, distribuição de status.

Exemplo

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

POST/listsUsuário

Criar nova lista

Nome obrigatório. Verifica o limite de listas conforme o plano.

Request body · application/json

Nome	Tipo	Obrig.	Descrição
`nombre`	`string`	Sim	Nome da lista
`from_email`	`string`	Não	Email remetente padrão
`from_name`	`string`	Não	Nome de remetente padrão
`descripcion`	`string`	Não	Descrição da lista

Exemplo

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

Resposta 201

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

Erros

Status	Code	Descrição
400	`name_required`	Nome obrigatório
400	`max_lists_reached`	Limite de listas atingido conforme o plano

GET/lists/:idUsuário

Detalhe completo da lista com estatísticas e campos personalizados

Parâmetros de rota

Nome	Descrição
`id`	ID numérico da lista

Exemplo

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

PUT/lists/:idUsuário

Atualizar propriedades da lista

Campos editáveis: nombre, from_email, from_name, descripcion, image_logo.

Parâmetros de rota

Nome	Descrição
`id`	ID numérico da lista

Request body · application/json

Nome	Tipo	Obrig.	Descrição
`nombre`	`string`	Não	Nome da lista
`from_email`	`string`	Não	Email remetente padrão
`from_name`	`string`	Não	Nome de remetente padrão
`descripcion`	`string`	Não	Descrição
`image_logo`	`string`	Não	URL do logotipo

Exemplo

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

Resposta 200

{ "success": true }

DELETE/lists/:idUsuário

Excluir lista permanentemente

Exclusão permanente e irreversível. Assinantes e campos personalizados são excluídos junto com a lista.

Parâmetros de rota

Nome	Descrição
`id`	ID numérico da lista

Exemplo

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

Resposta 200

{ "success": true }

POST/lists/:encid/exportUsuário

Exportar assinantes para CSV/XLSX

Parâmetros de rota

Nome	Descrição
`encid`	ID codificado da lista

Request body · application/json

Nome	Tipo	Obrig.	Descrição
`status`	`string`	Não	BKL, UNSUS, NOT_CONFIRMED, ACTIVE, SUBSCRIBED

Exemplo

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

Resposta 200

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

GET/lists/:id/customFieldsUsuário

Listar campos personalizados da lista

Parâmetros de rota

Nome	Descrição
`id`	ID numérico da lista

Exemplo

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

POST/lists/:id/customFieldsUsuário

Criar campo personalizado

Nome único na lista. Limite de campos não excedido.

Parâmetros de rota

Nome	Descrição
`id`	ID numérico da lista

Request body · application/json

Nome	Tipo	Obrig.	Descrição
`name`	`string`	Sim	Nome do campo
`type`	`string`	Sim	text, dropdown, radio, date, multiline
`required`	`boolean`	Não	Default: false
`internal`	`boolean`	Não	Campo interno, não visível ao assinante
`default`	`string`	Não	Valor padrão
`options`	`string[]`	Não	Opções para dropdown/radio

Exemplo

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/copyUsuário

Copiar campos personalizados de outra lista

Parâmetros de rota

Nome	Descrição
`id`	ID da lista de destino

Request body · application/json

Nome	Tipo	Obrig.	Descrição
`sourceListId`	`number`	Sim	ID da lista de origem

Exemplo

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/:fidUsuário

Detalhe do campo personalizado

Parâmetros de rota

Nome	Descrição
`id`	ID numérico da lista
`fid`	ID do campo personalizado

Exemplo

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

PUT/lists/:id/customField/:fidUsuário

Atualizar campo personalizado

Parâmetros de rota

Nome	Descrição
`id`	ID numérico da lista
`fid`	ID do campo personalizado

Request body · application/json

Nome	Tipo	Obrig.	Descrição
`name`	`string`	Não	Novo nome do campo
`required`	`boolean`	Não	Obrigatório
`default`	`string`	Não	Valor padrão
`options`	`string[]`	Não	Opções (dropdown/radio)

Exemplo

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

Resposta 200

{ "success": true }

DELETE/lists/:id/customField/:fidUsuário

Excluir campo personalizado

Parâmetros de rota

Nome	Descrição
`id`	ID numérico da lista
`fid`	ID do campo personalizado

Exemplo

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

Resposta 200

{ "success": true }

GET/lists/:id/subscribersUsuário

Listar assinantes com paginação

Parâmetros de rota

Nome	Descrição
`id`	ID numérico da lista

Query params

Nome	Tipo	Obrig.	Default	Descrição
`limit`	`number`	Não	`50`	Itens por página (máx. 100)
`offset`	`number`	Não	`0`	Deslocamento
`q`	`string`	Não	`-`	Busca por email ou nome
`status`	`string`	Não	`-`	active, unsubscribed, blocked, pending
`sortBy`	`string`	Não	`email`	email, nombre, cdate, lastOpen
`sortDir`	`string`	Não	`asc`	asc ou desc

Exemplo

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

Resposta 200

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

POST/lists/:id/subscribersUsuário

Criar assinante na lista

Parâmetros de rota

Nome	Descrição
`id`	ID numérico da lista

Request body · application/json

Nome	Tipo	Obrig.	Descrição
`email`	`string`	Sim	Email do assinante
`nombre`	`string`	Não	Nome
`confirmado`	`boolean`	Não	Default: true
`customFields`	`object`	Não	{ "fieldId": "value" }

Exemplo

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

Erros

Status	Code	Descrição
400	`email_required`	Email obrigatório
400	`invalid_email_format`	Formato de email inválido
409	`email_already_exists`	O email já existe na lista

GET/lists/:id/subscribers/:sidUsuário

Detalhe do assinante com campos personalizados

Parâmetros de rota

Nome	Descrição
`id`	ID numérico da lista
`sid`	ID do assinante

Exemplo

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

GET/lists/:id/subscribers/:sid/historyUsuário

Histórico de atividade do assinante

Parâmetros de rota

Nome	Descrição
`id`	ID numérico da lista
`sid`	ID do assinante

Exemplo

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

GET/lists/:id/subscribers/:sid/campaignsUsuário

Campanhas recebidas pelo assinante (últimos 90 dias)

Parâmetros de rota

Nome	Descrição
`id`	ID numérico da lista
`sid`	ID do assinante

Exemplo

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

PUT/lists/:id/subscribers/:sidUsuário

Atualizar dados do assinante

Parâmetros de rota

Nome	Descrição
`id`	ID numérico da lista
`sid`	ID do assinante

Request body · application/json

Nome	Tipo	Obrig.	Descrição
`nombre`	`string`	Não	Nome
`customFields`	`object`	Não	{ "fieldId": "value" }

Exemplo

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

Resposta 200

{ "success": true }

POST/lists/:id/tools/bulk-unsubscribeUsuário

Cancelar inscrição/excluir assinantes em massa

Operação assíncrona. Progresso em tempo real via Socket.io (evento: bulkOperationProgress).

Parâmetros de rota

Nome	Descrição
`id`	ID numérico da lista

Request body · application/json

Nome	Tipo	Obrig.	Descrição
`emails`	`string[]`	Sim	Array de emails a processar
`action`	`string`	Sim	"unsubscribe" ou "delete"
`scope`	`string`	Sim	"list" (somente esta lista) ou "global" (todas as listas)

Exemplo

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

Resposta 200

{ "started": true }

POST/lists/:id/tools/remove-inactiveUsuário

Excluir assinantes inativos

Operação assíncrona com progresso via Socket.io.

Parâmetros de rota

Nome	Descrição
`id`	ID numérico da lista

Request body · application/json

Nome	Tipo	Obrig.	Descrição
`days`	`number`	Sim	Dias de inatividade para considerar inativo
`action`	`string`	Sim	"unsubscribe" ou "delete"

Exemplo

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

Resposta 200

{ "started": true }

GET/lists/:id/tools/preview-inactiveUsuário

Pré-visualização de assinantes inativos

Parâmetros de rota

Nome	Descrição
`id`	ID numérico da lista

Query params

Nome	Tipo	Obrig.	Default	Descrição
`days`	`number`	Sim	`-`	Dias de inatividade

Exemplo

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

Resposta 200

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

POST/lists/tools/inactive-cleanup/previewUsuário

Pré-visualização de limpeza flexível de contatos inativos

Permite pré-visualizar contatos inativos em uma ou mais listas antes de executar a operação.

Request body · application/json

Nome	Tipo	Obrig.	Descrição
`listIds`	`array`	Sim	IDs numéricos ou codificados de listas
`days`	`number`	Sim	30, 60, 90, 120, 180 ou 365
`activity`	`string`	Sim	opens_or_clicks, opens ou clicks

Exemplo

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

Resposta 200

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

POST/lists/tools/inactive-cleanup/executeUsuário

Executar limpeza flexível de contatos inativos

Operação assíncrona com progresso via Socket.io.

Request body · application/json

Nome	Tipo	Obrig.	Descrição
`listIds`	`array`	Sim	IDs numéricos ou codificados de listas
`days`	`number`	Sim	30, 60, 90, 120, 180 ou 365
`activity`	`string`	Sim	opens_or_clicks, opens ou clicks
`action`	`string`	Sim	unsubscribe ou delete

Exemplo

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

Resposta 200

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

POST/lists/:id/tools/import/analyzeUsuário

Analisar arquivo de importação

Content-Type: multipart/form-data. Suporta .xlsx, .xls, .csv, .txt (máx. 20MB) ou texto simples no campo "text". Retorna formato, headers, preview e fileId.

Parâmetros de rota

Nome	Descrição
`id`	ID numérico da lista

Request body · multipart/form-data

Nome	Tipo	Obrig.	Descrição
`file`	`file`	Não	Arquivo .xlsx, .xls, .csv ou .txt (máx. 20MB)
`text`	`string`	Não	Texto simples com emails (alternativa a file)

Exemplo

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

Erros

Status	Code	Descrição
400	`no_input`	Nenhum arquivo ou texto foi enviado

POST/lists/:id/tools/import/executeUsuário

Executar importação de assinantes

Processa em segundo plano com progresso em tempo real via Socket.io (evento: importProgress). Requer fileId (da análise anterior) ou text.

Parâmetros de rota

Nome	Descrição
`id`	ID numérico da lista

Request body · application/json

Nome	Tipo	Obrig.	Descrição
`fileId`	`string`	Não	ID do arquivo analisado anteriormente
`text`	`string`	Não	Texto simples alternativo
`columnMapping`	`object`	Sim	Mapeamento de colunas { columnIndex: fieldName }

Exemplo

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

Resposta 200

{ "started": true }

Erros

Status	Code	Descrição
400	`no_input`	Nenhum dado foi enviado
400	`no_email_column`	Coluna de email não mapeada
400	`file_not_found`	FileId não existe ou expirou

Comece com o arrobaMail
em menos de 5 minutos.

Plano Gratuito, gerações de IA incluídas, sem cartão de crédito e suporte real em português.

Testar grátis agora

Lists /lists

Listar listas com estatísticas

Dashboard de análise de listas

Criar nova lista

Detalhe completo da lista com estatísticas e campos personalizados

Atualizar propriedades da lista

Excluir lista permanentemente

Exportar assinantes para CSV/XLSX

Listar campos personalizados da lista

Criar campo personalizado

Copiar campos personalizados de outra lista

Detalhe do campo personalizado

Atualizar campo personalizado

Excluir campo personalizado

Listar assinantes com paginação

Criar assinante na lista

Detalhe do assinante com campos personalizados

Histórico de atividade do assinante

Campanhas recebidas pelo assinante (últimos 90 dias)

Atualizar dados do assinante

Cancelar inscrição/excluir assinantes em massa

Excluir assinantes inativos

Pré-visualização de assinantes inativos

Pré-visualização de limpeza flexível de contatos inativos

Executar limpeza flexível de contatos inativos

Analisar arquivo de importação

Executar importação de assinantes

Comece com o arrobaMailem menos de 5 minutos.

Lists `/lists`

Comece com o arrobaMail
em menos de 5 minutos.