Docs / Módulo / Mailing

Módulo de Mailing

Envía newsletters y campañas masivas con segmentación, personalización, programación y métricas en tiempo real.

Introducción

El módulo de Mailing te permite administrar listas de contactos, crear campañas y enviar correos de alto volumen con seguimiento de aperturas y clics. Integra por API, SDK o consola.

Incluye

• Listas, segmentos y campos personalizados
• Plantillas HTML + variables
• Programación y envíos por lote
• Métricas y webhooks

Uso ideal

• Newsletters semanales
• Campañas promocionales
• Emails transaccionales (opcional)

Conceptos

Contacto

Registro con email y atributos (nombre, tags, campos custom). Puede pertenecer a varias listas.

Lista

Conjunto de contactos. Se usa como base para campañas y segmentos.

Segmento

Filtro dinámico (por tags, actividad, campos). Define quién recibe una campaña.

Campaña

Contenido (HTML + asunto) + audiencia + programación. Produce envíos y métricas.

Quickstart

Flujo típico: crear lista → agregar contactos → crear campaña → enviar (o programar).

1) Crear lista

POST /mail/lists
{
  "name": "Clientes Pro",
  "description": "Lista principal"
}

2) Agregar contacto

POST /mail/contacts
{
  "email": "cliente@dominio.com",
  "first_name": "Ana",
  "tags": ["pro","mx"]
}

3) Crear campaña

POST /mail/campaigns
{
  "name": "Newsletter Enero",
  "from_name": "Webability",
  "from_email": "news@tudominio.com",
  "subject": "Novedades de enero",
  "list_id": "lst_123",
  "html": "<h1>Hola {{first_name}}</h1>..."
}

4) Enviar

POST /mail/campaigns/cmp_123/send
{
  "schedule_at": null
}

Listas y contactos

Endpoint	Método	Descripción
/mail/lists	GET/POST	Listar / crear listas.
/mail/lists/{id}	GET/PATCH/DELETE	Detalle / actualizar / eliminar.
/mail/contacts	GET/POST	Listar / crear contactos.
/mail/lists/{id}/contacts	POST/DELETE	Agregar / quitar contacto de lista.
/mail/segments	GET/POST	Crear segmentos con filtros.

Consejo: usa tags y campos custom para segmentación flexible (ej. país, plan, actividad).

Campañas

Endpoint	Método	Descripción
/mail/campaigns	GET/POST	Listar / crear campañas.
/mail/campaigns/{id}	GET/PATCH/DELETE	Detalle / editar / eliminar.
/mail/templates	GET/POST	Plantillas reutilizables.

Variables de personalización

Hola {{first_name}},
Tu plan: {{plan}}
País: {{country}}

Envío y programación

Enviar ahora

POST /mail/campaigns/{id}/send
{ "schedule_at": null }

Programar

POST /mail/campaigns/{id}/send
{ "schedule_at": "2026-01-10T15:00:00-06:00" }

El envío puede procesarse por lotes. Puedes consultar el estado y el progreso desde la consola o por API.

Métricas

Consulta métricas de campaña: entregados, aperturas, clics, rebotes, bajas, quejas.

Ejemplo

GET /mail/campaigns/{id}/stats

Métrica	Descripción
delivered	Correos entregados al servidor destino.
opens	Aperturas (según tracking).
clicks	Clics en enlaces trackeados.
bounces	Rebotes duros y suaves.
unsubscribes	Bajas.

Webhooks

Recibe eventos en tu backend: delivered, opened, clicked, bounced, unsubscribed, complaint.

Ejemplo evento

POST https://tuapp.com/webhooks/mail
{
  "event": "opened",
  "campaign_id": "cmp_123",
  "contact": "cliente@dominio.com",
  "ts": "2026-01-07T22:15:10-06:00",
  "meta": { "ip": "1.2.3.4", "ua": "..." }
}

Errores

HTTP	Código	Descripción
400	invalid_params	Campos faltantes o inválidos.
401	unauthorized	API key inválida o sin permisos.
429	rate_limited	Límite de requests excedido.
500	send_error	Error interno de envío o cola.

SDKs

SDKs disponibles para integrar en tu aplicación (Go, Node, PHP, etc.). Aquí puedes colocar ejemplos reales.

go get webability.info/wamail

Node

npm i @webability/mail

PHP

composer require webability/mail