REST API · v1

Un token. Cada endpoint.

Una API HTTP limpia y orientada a recursos para campañas, listas, suscriptores, automatizaciones, servidores de envío y facturación de clientes. Autentíquese con un solo token, consulte JSON y entregue en minutos. La misma API que usan los plugins es la que usan los clientes externos: sin endpoints de segunda clase.

Inicio rápido en 4 pasos ↓ Catálogo de endpoints

Lo que puede construir

Frontend SaaS App móvil Sincronización con CRM Disparadores de automatización Paneles de revendedor

POR QUÉ ESTA API

Sin sorpresas. Sin endpoints de segunda clase.
La misma API que usan sus plugins.

Autenticada por token

Cada petición lleva un único token bearer. Generado por usuario desde Perfil → Token de API. Pásela vía cabecera Authorization: Bearer o por query string ?api_token=. Revoque y rote en cualquier momento.

Orientada a recursos

Cada concepto es un recurso con verbos predecibles. GET /lists devuelve la colección, POST /lists crea uno, PATCH /lists/:uid actualiza, DELETE /lists/:uid elimina. Los subrecursos se anidan de forma natural: /lists/:uid/subscribers.

La misma que usan los plugins

No hay división interno-vs-externo. Los endpoints a los que llega la propia UI de AcelleMail, los que su plugin extiende y los que lee su cliente externo son idénticos. Vea el SDK de plugins →

Endpoint autoalojado

La URL base es su propio servidor: https://your-acelle.example.com/api/v1/. Sin proxy del proveedor, sin límite de frecuencia compartido, sin tarifa por petición. El rendimiento es el que dé su hardware.

INICIO RÁPIDO

De cero a la primera respuesta en cuatro pasos.

Cada instalación de AcelleMail aloja su propia API en /api/v1/. Sustituya your-acelle.example.com por el hostname de su instalación.

STEP 1

Genere un token

Inicie sesión en su instalación de AcelleMail. Abra su menú de perfil y haga clic en Token de API. Copie el valor: es único por usuario y está ligado a los permisos de ese usuario.

# In your shell:
$ export ACELLE_TOKEN=paste-your-token-here
$ export ACELLE_BASE=https://your-acelle.example.com

STEP 2

Verifique el token

Llame a /me. Si el token es válido, recibe su registro de usuario. Si no, obtiene un 401: compruebe el token y la URL base.

$ curl $ACELLE_BASE/api/v1/me \
    -H "Authorization: Bearer $ACELLE_TOKEN"

{ "id": 1, "email": "you@…", "uid": "…" }

STEP 3

Cree una lista

Los recursos se crean con POST. Los campos del cuerpo obligatorios para una lista de correo son name, from_email, from_name, subject más un bloque de contacto.

$ curl -X POST $ACELLE_BASE/api/v1/lists \
    -H "Authorization: Bearer $ACELLE_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "name":       "Newsletter",
      "from_name":  "Acme",
      "from_email": "hi@acme.com",
      "subject":    "Welcome"
    }'

STEP 4

Añada un suscriptor

Use el UID de la lista del paso 3. Los campos personalizados se pasan como parámetros en mayúsculas (FIRST_NAME, LAST_NAME, …) coincidiendo con la configuración de campos de su lista.

$ curl -X POST $ACELLE_BASE/api/v1/subscribers \
    -H "Authorization: Bearer $ACELLE_TOKEN" \
    -d list_uid=$LIST_UID \
    -d EMAIL=alice@example.com \
    -d FIRST_NAME=Alice \
    -d tag=newsletter,beta

RECURSOS

Ocho recursos. Más de cuarenta endpoints. Cada verbo que cabría esperar.

Todos los endpoints de abajo están bajo el namespace /api/v1/ y requieren autenticación por token auth:api salvo que se indique lo contrario. Las acciones del ciclo de vida (run, pause, resume) se exponen como subrutas POST. Las descargas de log envían en streaming el CSV subyacente.

Autenticación

Todos los endpoints autenticados aceptan el token vía la cabecera Authorization: Bearer (preferido) o el parámetro de consulta ?api_token= (legacy). Use POST /user/login para intercambiar email + contraseña por un token fresco desde un cliente programático.

POST/user/loginIntercambie email + contraseña por un token de API. Endpoint público.

GET/meDevuelve el registro del usuario autenticado. Úselo para verificar un token.

POST/login-tokenGenere una URL de inicio de sesión de un solo uso en la que el usuario puede hacer clic para entrar autenticado.

Listas

Las listas de correo son el contenedor principal para los suscriptores. Cada lista viene con una identidad de remitente por defecto, campos personalizados y ajustes de doble opt-in / email de bienvenida. Los campos personalizados se añaden con la subruta add-field.

GET/listsÍndice paginado de listas propiedad del usuario del token.

POST/listsCree una lista nueva. Obligatorios: name, from_email, from_name, subject + bloque de contacto.

GET/lists/:uidObtenga una sola lista con sus campos y estadísticas.

PATCH/lists/:uidActualice los metadatos de la lista, la identidad del remitente o los ajustes de opt-in.

POST/lists/:uid/add-fieldAñada un campo personalizado. El tipo es text, number o datetime.

DELETE/lists/:uidElimine permanentemente una lista y todos sus suscriptores.

Suscriptores

Los suscriptores pertenecen a una lista y llevan valores de campos personalizados, etiquetas e historial de aperturas/clics. El estado es uno de subscribed, unsubscribed o unconfirmed. Las operaciones de etiqueta son aditivas e idempotentes.

GET/subscribers?list_uid=…Índice paginado. Filtre con open=yes|no, click=yes|no.

POST/subscribersCree. Obligatorios: list_uid, EMAIL. Los campos personalizados como parámetros en mayúsculas.

GET/subscribers/:idObtenga un solo suscriptor por id o email.

GET/subscribers/email/:emailEncuentre cada lista que tiene un suscriptor con este email.

PATCH/subscribers/:idActualice campos, etiquetas o estado.

POST/subscribers/:id/add-tagAñada etiquetas separadas por comas.

POST/subscribers/:id/remove-tagQuite etiquetas separadas por comas.

PATCH/lists/:list_uid/subscribers/:id/subscribeMarque como subscribed.

PATCH/lists/:list_uid/subscribers/:id/unsubscribeMarque como unsubscribed.

PATCH/lists/:list_uid/subscribers/email/:email/unsubscribeDé de baja por email cuando no tenga el id.

DELETE/subscribers/:idBorrado duro de la lista.

Campañas

Las campañas son la unidad de envío. Cree una con contenido HTML + flags de seguimiento, hágala transitar a run / pause / resume y luego descargue como CSV los logs de seguimiento, aperturas, clics, rebotes, feedback y bajas.

GET/campaignsÍndice paginado. Pase per_page, page.

POST/campaignsCree. Obligatorios: list_uid, name, subject, from_*, html.

GET/campaigns/:uidObtenga una sola campaña con estadísticas.

PATCH/campaigns/:uidActualice contenido, asunto o flags de seguimiento.

POST/campaigns/:uid/runEncole la campaña para entrega.

POST/campaigns/:uid/pausePause una campaña en curso.

POST/campaigns/:uid/resumeReanude una campaña en pausa.

GET/campaigns/:uid/tracking-log/downloadStremee el CSV de seguimiento.

GET/campaigns/:uid/{open,click,bounce,feedback,unsubscribe}-log/downloadStremee el CSV por evento (una ruta por tipo de evento).

DELETE/campaigns/:uidElimine una campaña (solo cuando no esté en curso).

Automatizaciones

Las automatizaciones son flujos visuales de disparadores, condiciones y acciones. La API expone la vista de lectura más dos formas de disparar flujos desde sistemas externos: execute para ejecutar toda una automatización, o api/call para disparar un nodo «llamada de API» a mitad del flujo.

GET/automationsÍndice de automatizaciones propiedad del usuario del token.

POST/automations/:uid/executeDispare una automatización para un suscriptor. Útil para flujos transaccionales.

POST/automations/:uid/api/callDispare un nodo de disparador «llamada de API» a mitad del flujo con un payload personalizado.

Servidores de envío

Los servidores de envío son los transportes configurables (SMTP, Amazon SES, SendGrid, Mailgun, Postmark, drivers a medida desde plugins). Gestiónelos de forma programática al aprovisionar nuevos tenants o al rotar credenciales.

GET/sending_serversÍndice de servidores de envío configurados.

POST/sending_serversCree un servidor de envío nuevo. Configuración específica del driver bajo settings.

GET/sending_servers/:uidObtenga un solo servidor de envío.

PATCH/sending_servers/:uidActualice ajustes o rote credenciales.

DELETE/sending_servers/:uidQuite un servidor de envío (las campañas que lo referencian deben re-enrutarse primero).

Añadir un nuevo transporte (Postal MTA, una API HTTP a medida, …) es un hook REGISTRY: entréguelo como plugin en lugar de parchear el core.

Clientes ADMIN

Los endpoints de clientes están restringidos a tokens de administrador. Úselos para aprovisionar cuentas de tenants, gestionar suscripciones, cambiar de plan o generar URLs de inicio de sesión de un solo uso para soporte o impersonación.

GET/customersÍndice paginado de todos los clientes.

POST/customersCree una nueva cuenta de cliente + usuario.

GET/customers/by-email/:emailBusque un cliente por email.

PATCH/customers/:uidActualice el perfil / contacto / cuota del cliente.

PATCH/customers/:uid/{enable,disable}Suspenda o reactive el acceso sin borrar datos.

POST/customers/:uid/change-plan/:plan_uidCambie un cliente a un plan diferente (cargos, prorrateos, renovación de la suscripción).

POST/customers/:uid/assign-plan/:plan_uidAsigne un plan sin flujo de facturación (override de admin).

POST/customers/:uid/subscription/updateActualice los parámetros de una suscripción activa.

POST/login-tokenGenere una URL de inicio de sesión de un solo uso para el cliente objetivo.

Suscripciones ADMIN

Las suscripciones ligan a un cliente con un plan + cadencia de facturación. Use estos endpoints al integrar con sistemas externos de facturación o al auditar los ingresos recurrentes.

GET/subscriptionsÍndice de todas las suscripciones activas.

POST/subscriptionsCree un registro de suscripción (normalmente dirigido por el webhook de su pasarela).

GET/subscriptions/:uidObtenga una sola suscripción con su historial de renovaciones.

PATCH/subscriptions/:uidAjuste la cuota, la cadencia o la fecha de fin.

Archivos

Suba imágenes y otros assets para usarlos en el contenido de la campaña. El endpoint acepta multipart/form-data y devuelve una URL pública a la que puede hacer referencia en el cuerpo HTML.

POST/file/uploadSuba un archivo. Devuelve { "url": "..." }.

Plugins y actualizaciones ADMIN

Instale plugins de forma programática desde una URL de descarga, ejecute actualizaciones remotas del core en un flujo de petición en dos pasos (para que el paso 2 aterrice en un worker PHP fresco) o refresque la licencia. Útil para operadores de flota que gestionan muchos tenants de AcelleMail.

POST/plugins/installInstale un plugin desde una URL de descarga.

POST/upgrade/runInicie una actualización remota del core (descarga + extracción).

POST/upgrade/run-fileAplique un solo paso de migración.

POST/upgrade/finalizeFinalice una actualización. Debe llamarse como una petición fresca después de run.

POST/license/refreshRefresque la información de la licencia de CodeCanyon (refleja Administración → Licencia).

WEBHOOKS

Empuje los eventos hacia fuera, en lugar de hacer polling.

AcelleMail entrega dos superficies de webhook. Los webhooks del ciclo de vida se disparan en transiciones de cliente + suscripción + automatización y se configuran globalmente. Los pings de seguimiento por destinatario se disparan en aperturas / clics / bajas y se configuran por campaña. Ambos reintentan en caso de fallo con backoff exponencial.

Webhooks del ciclo de vida

Transiciones de cliente + suscripción

Configurados una vez en Administración → Ajustes → Webhooks. Cada webhook es un nombre + evento + configuración HTTP saliente (URL, método, cabeceras, plantilla de cuerpo). Vienen seis eventos en el core:

new_customer — parámetros: customer_id
new_subscription — customer_id, plan_id
change_plan — customer_id, old_plan_id, new_plan_id
cancel_subscription — customer_id, plan_id
terminate_subscription — customer_id, plan_id
automation_webhook — automation_id (se dispara desde nodos llamada de API)

La política de reintentos es por webhook: retry_times configurable (por defecto 2) y retry_after_seconds (por defecto 900). Las entregas fallidas se registran, se reintentan y aparecen en el log de webhooks de administración.

Los plugins pueden registrar eventos adicionales vía el patrón de hook EVENT: acelle/ai, por ejemplo, dispara ai_task_completed desde sus listeners a medida.

Seguimiento por destinatario

Aperturas, clics, bajas

Configurados por campaña o por plantilla de email en Seguimiento → Webhooks. Tres tipos de evento se disparan a medida que el destinatario interactúa con el mensaje:

open — el destinatario abrió el email (píxel de seguimiento)
click — el destinatario hizo clic en un enlace con seguimiento
unsubscribe — el destinatario pulsó el enlace de baja

Cada ping lleva el uid de la campaña, el email del suscriptor y la URL del clic (para eventos click). Configure tantos webhooks de seguimiento como necesite por campaña: útil para reflejar en paralelo a analítica + CRM + data warehouse.

Los eventos a nivel de servidor de envío (rebote, queja, entrega) fluyen por el stack interno de listeners App\SendingServers\Webhooks\*: se muestran en los endpoints de log de campaña en lugar de como webhooks salientes. Descargar CSVs de log →

Ejemplo: payload de `new_subscription`

POST /your-webhook-url
Content-Type: application/json
X-AcelleMail-Event: new_subscription
X-AcelleMail-Signature: sha256=…

{
  "event":       "new_subscription",
  "customer_id": 1234,
  "plan_id":     "extended-monthly",
  "fired_at":    "2026-05-06T12:34:56Z"
}

Ejemplo: payload de seguimiento de `click`

POST /your-webhook-url
Content-Type: application/json
X-AcelleMail-Event: click

{
  "event":         "click",
  "campaign_uid":  "abc123",
  "subscriber":    "alice@example.com",
  "url":           "https://acme.com/promo",
  "clicked_at":    "2026-05-06T12:34:56Z"
}

RESPUESTAS Y ERRORES

JSON predecible. Códigos de estado convencionales.

Cada respuesta exitosa es JSON. Cada respuesta fallida es JSON, con un message de nivel superior y un mapa errors para los fallos de validación. Los códigos de estado siguen la convención REST: puede ramificar su cliente solo según el código.

Código	Cuándo lo verá
200 OK	Lectura o actualización exitosa.
201 Created	Creación exitosa.
401 Unauthorized	Token ausente o inválido.
403 Forbidden	Token válido, pero el recurso no es suyo o no es de admin.
404 Not Found	El UID no existe.
422 Unprocessable	Error de validación. Compruebe el mapa `errors` en el cuerpo.
500 Server	Bug del lado del servidor. Revise `storage/logs/laravel.log`.

Error de validación (422)

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json

{
  "message": "The given data was invalid.",
  "errors": {
    "from_email": [
      "The from_email field is required."
    ],
    "subject": [
      "The subject must be at most 998 characters."
    ]
  }
}

Fallo de autenticación (401)

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{ "message": "Unauthenticated." }

Paginación

Los endpoints de índice aceptan per_page (por defecto 10–25 según el recurso) y page. Las respuestas incluyen la forma estándar del paginador de Laravel: data[], links, meta.current_page, meta.total.

Límites de frecuencia

El límite de frecuencia lo decide usted: configúrelo en su instalación de Laravel vía RouteServiceProvider. Las builds de fábrica vienen sin throttle de API, ya que está llegando a su propio servidor. Añada throttle:60,1 si quiere uno.

Versionado

La versión mayor actual es v1. Los endpoints nuevos se añaden libremente; los cambios incompatibles a endpoints existentes se entregarían como v2 junto a v1. Fije su cliente a /api/v1/ y estará estable.

CLIENTES

Cualquier cliente HTTP. Sin SDK propietario.

No hay ningún SDK de AcelleMail que instalar. La API habla JSON sobre HTTP: use el cliente que ya tenga su stack. Tres de los más habituales en la práctica:

curl · one-liners

curl $ACELLE_BASE/api/v1/lists \
  -H "Authorization: Bearer $ACELLE_TOKEN" \
  | jq '.data[].name'

Cliente HTTP de Laravel

$resp = Http::withToken($token)
    ->baseUrl($base.'/api/v1')
    ->post('/subscribers', [
        'list_uid' => $listUid,
        'EMAIL'    => $email,
    ]);

return $resp->json();

fetch de navegador / Node

const r = await fetch(
  `${base}/api/v1/campaigns/${uid}/run`,
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${token}`,
    },
  }
);
const data = await r.json();

¿Está construyendo un SDK de código abierto? Escríbanos: lo enlazaremos desde esta página.

REFERENCIA CANÓNICA

La referencia completa y ejecutable de la API.

Cada parámetro. Cada forma de retorno. Cada ejemplo de curl funcional. Alojada en la instalación de demo canónica: el mismo código que ejecuta su instalación.

api.acellemail.com

Sustituya api.acellemail.com por el hostname de su propia instalación al llamar.

RECURSOS Y COMUNIDAD

Construya con la API, entregue como plugin y pregunte cuando se atasque.

EMPEZAR A CONSTRUIR

Ejecute AcelleMail. Obtenga un token. Haga una llamada.

Licencia de pago único. Código fuente completo. Endpoint autoalojado. La API está incluida: sin complemento, sin plan de tarifa.

Obtenga AcelleMail — $80 SDK de plugins →