Elixir y Liquid

Elixir es el módulo de envío masivo personalizado: subes un CSV o XLSX, escribes una plantilla Liquid y BloomX envía un correo por fila, con reintentos, cuotas, lista de supresión y baja de un clic. Hay dos modos: envío directo por lotes en primer plano y campañas en segundo plano persistentes.

Datos de entrada#

• Archivo de hasta 15 MB; hasta 100 000 filas y 500 columnas. CSV/TXT (quita BOM, detecta , ; tab o |, o respeta sep=;; RFC 4180) y XLSX (solo la primera hoja, con protección anti zip-bomb; el .xls antiguo se rechaza).
• Cabeceras vacías pasan a columna_N y duplicadas a nombre_2. Cada celda se recorta a 20 000 caracteres.
• Los nombres de columna pueden llevar espacios y acentos; para símbolos usa row["Precio (S/.)"].
• El editor es CodeMirror con autocompletado y *lint* de la plantilla; hay biblioteca de plantillas (máx. 200 por usuario) e historial de campañas.

Liquid: sintaxis y límites#

El motor Liquid es propio (no la librería estándar): compila una vez y renderiza por fila; los errores de sintaxis, etiqueta o filtro desconocido se detectan al compilar. Sin eval ni Function; solo se leen propiedades propias.

Hola {{ nombre | capitalize }},

{% if saldo > 0 %}
Tienes un saldo pendiente de S/ {{ saldo | round: 2 }} con vencimiento el {{ vence | date: "%d/%m/%Y" }}.
{% else %}
¡Gracias por estar al día!
{% endif %}

{% assign items = "A,B,C" | split: "," %}
{% for item in items limit: 2 %}
  {{ forloop.index }}. Producto {{ item }}
{% endfor %}

Enviado el {{ current_date }}.
Si no deseas recibir más correos: {{ unsubscribe_url }}

Etiquetas (tags)#

• if / elsif / else, unless, for (con limit, offset, reversed, rangos (1..N) y else), case / when (coma u or), assign, capture, comment, raw, increment, decrement, cycle, echo, break, continue.
• Control de espacios: {{-, -}}, {%-, -%}. Operadores: ==, !=, >, <, >=, <=, contains, and, or.
• forloop: index, index0, rindex, rindex0, first, last, length, parentloop.
• No soportados (error explícito): include, render, liquid, tablerow, ifchanged y similares.
• Diferencias con Liquid estándar: una celda vacía, "false", "nil" o "null" cuenta como falsa; las fechas YYYY-MM-DD y DD/MM/YYYY se tratan como fecha de calendario (sin zona horaria).

Filtros#

fixed y push no son estándar de Liquid.

Variables#

• Las columnas de tu archivo.
• current_date, current_day, current_month, current_year (las calcula el servidor, en español, con la zona de la campaña) y now / today (para usar con | date).
• unsubscribe_url: enlace de baja firmado por destinatario.
• brand_name, brand_color, brand_logo aparecen como variables de sistema en el editor, pero el servidor no las calcula: solo llegan si el cliente las manda en systemVars (máx. 50 claves).
• Precedencia al fusionar: fecha < systemVars < fila < unsubscribe_url.
• Opciones de render: autoescape (por defecto activo; usa | raw para valores de confianza), strictVariables (por defecto activo) y timezone (zona IANA, por defecto UTC).

Modos de envío#

Envío directo por lotes#

POST /api/elixir/send desde la interfaz, en lotes de 25 (el servidor acepta hasta ELIXIR_BATCH_MAX = 50 filas, tope 100) con presupuesto de 45 s. Devuelve results por fila (sent, skipped, error, unsubscribed) y pending, con retryAfterMs o paused: "quota". Límite de 1200 peticiones por hora por usuario y cuota en memoria ELIXIR_MAX_ROWS_PER_HOUR (5000 por defecto). Idempotente por (campaña, destinatario) con Idempotency-Key hacia Resend.

Campañas en segundo plano#

POST  /api/elixir/campaigns                    -> crea el borrador (compila y valida la plantilla)
POST  /api/elixir/campaigns/<id>/rows           -> sube filas en trozos de hasta 500 ({ items: [{ index, row }] })
PATCH /api/elixir/campaigns/<id>  {"action":"start"}   (pause | resume | cancel | retry_errors)
GET   /api/elixir/campaigns/<id>?rows=1         -> estado y filas
# El worker avanza con /api/cron/elixir (Authorization: Bearer <CRON_SECRET>) o POST /api/elixir/campaigns/<id>/tick (1 cada 10 s)

• Hasta 20 000 filas por campaña (ELIXIR_MAX_CAMPAIGN_ROWS; 413 al excederlo). Al subir, un correo inválido pasa a skipped (invalid_email) y un duplicado a skipped (duplicate).
• Estados de campaña: draft → running ⇄ paused, y running → done | cancelled | failed. start solo desde draft; resume desde paused, cancelled o failed; retry_errors devuelve las filas error a pending. Borrar una campaña running da 409.
• Estados de fila: pending → sending → sent | error | skipped | unsubscribed, y sent → bounced | complained (por eventos de Resend).
• Worker (/api/cron/elixir, Authorization: Bearer <CRON_SECRET> o la clave interna derivada): hasta 5 campañas en marcha, un solo worker por campaña (bloqueo de 90 s), lotes de 10 filas con 550 ms entre envíos, cuota persistente por usuario (filas sent de la última hora, ELIXIR_MAX_ROWS_PER_HOUR). Filas atascadas en sending más de 5 min vuelven a pending.
• Reintentos: hasta 4 dentro de un envío (backoff exponencial con jitter, respeta Retry-After) y, por fila, backoff 30 s × 2^(n−1) con tope de 1 h y máximo 6 intentos (después error con código max_attempts). Con 429/5xx/red la fila vuelve a pending y el lote se detiene.
• Falla cerrado: si la lista de supresión no está disponible, no envía y reintenta a los 30 s. Si el render falla, la fila queda en error: nunca se envía la plantilla cruda. El remitente debe ser el usuario o una cuenta vinculada.
• Elixir no tiene cron programado en el repositorio: avanza por encadenamiento propio (hasta 400 saltos), por el sondeo de la interfaz o por un cron externo (Despliegue).

Supresión y bajas#

• Cada envío masivo añade List-Unsubscribe (https y mailto:) y List-Unsubscribe-Post: List-Unsubscribe=One-Click (RFC 8058) solo si NEXT_PUBLIC_APP_URL es https y hay secreto (UNSUBSCRIBE_SECRET o NEXTAUTH_SECRET). Se añade un pie de baja salvo que la plantilla ya use unsubscribe_url.
• GET /api/webhooks/unsubscribe?t=<token> muestra una página de confirmación y no da de baja; POST da de baja (un clic o formulario). Página bilingüe (?lang=), sin JavaScript; 30/min por IP.
• Las bajas se guardan como eventos. Los rebotes permanentes y las quejas de Resend (webhook resend-events) también suprimen; el retraso de entrega solo se anota.
• Los destinatarios suprimidos se omiten en cada envío (unsubscribed). cc y bcc admiten Liquid (máx. 10 extras, filtrando suprimidos).

Límites conocidos#

• El worker siempre renderiza con locale = es para las variables de fecha.
• La cuota ELIXIR_MAX_ROWS_PER_HOUR del modo directo es por instancia (memoria); la del worker es persistente.
• Las plantillas y campañas persistidas no incluyen adjuntos.
• Sin CRON_SECRET y sin cron propio, las campañas dependen de tener la interfaz abierta o del encadenamiento.