Ir al contenido
JoeCMS Descargar 3.1.5
Manual · 06

Email, notificaciones, SMS y push

El CMS sabe enviar: emails transaccionales con plantillas y adjuntos, notificaciones in-app, SMS y push mediante proveedores. No todo está conectado al mismo nivel: esta página dice qué está listo, qué está presente pero por configurar y qué es andamiaje upstream.

1. Panorama

CanalMotorEstado en el repo
Email transaccionalprocess_mail() + PHPMailer (SMTP)en producción: registro, activación, recuperación de contraseña
Email (abstracción por servicios)Mailer (vendor/wolfgan/mailer/)presente; servicios email_localhost (SMTP) y email_sparkpost
Notificaciones in-appNotifier (vendor/hcore/notifier/) + sección de backend /restricted/notifypresente, con widget y applet
Push navegador/appdriver push_onesignal + servicio notification.onesignallisto, requiere App ID y clave REST
SMSdrivers sms_joesmtp / sms_twilio + servicios sms.joesmtp / sms.twiliolisto, requiere credenciales
Segundo factor en el loginAuth::login + canal email o SMS del Notifierapagado por defecto (AUTH_2FA), ver 08
Vista previa de emailscontents/emailpreviewer/, /srv/email-preview (regla en modules/cms-common)presente

2. Emails transaccionales

Configuración

El instalador escribe en themes/site/conf/config.remote.php:

define("A_SMTP_HOST", "");  define("A_SMTP_PORT", 465);  define("A_SMTP_SECURE", "ssl");
define("A_SMTP_USER", "");  define("A_SMTP_PASSWORD", "");

Las lee vendor/wolfgan/mailer/services/email_localhost.php (y su equivalente sparkpost). El asistente hace un envío de prueba durante la instalación, con un cliente SMTP autónomo (SSL 465 / STARTTLS 587 / plain): el correo se verifica antes de terminar, no con el primer usuario que se registra.

Enviar

process_mail($email_struct, $to, $subject, $tpl_email_path, $fields,
             $from, $bcc, $cc, $preview, $enable_check, $invert_mail,
             $owner, $body, $attach, $prefix);

library/gallery/process/mail.php construye una estructura con tema, dominio, idioma y parámetros SMTP, luego resuelve la plantilla y envía. Las plantillas están en themes/<tema>/contents/email/ — en el repo, auth/activation_code.html, auth/recover_code.html y auth/account_code.html (el código del 2FA), con las imágenes en email/images/. Sus textos son códigos del diccionario (svc_mail_*), así que el email sale en el idioma de composición (abajo); hasta la 3.0.3 estaban escritos en italiano dentro del archivo.

En qué idioma sale un email

El idioma del destinatario, no el de la petición. FF_LOCALE sirve para los envíos síncronos (quien recibe es quien acaba de hacer clic), pero en un cron o en un job asíncrono — recordatorios, vencimientos, listas de espera, renovaciones — no hay ninguna petición, y FF_LOCALE valdría el predeterminado para todos. Por eso la preferencia de idioma está en el perfil (access_users.locale / access_users.ID_lang, ver 07 §3) y la leen los helpers de library/gallery/common/language_preference.php:

HelperCuándo
language_pref_for_user($ID_user)se tiene el ID: emails, notificaciones, PDF, SMS generados por cron/job
language_pref_for_email($email)solo se tiene la dirección; responde null si es desconocida o si varias cuentas con esa dirección tienen preferencias distintas

Orden: perfil del destinatario → idioma de la petición (solo si es síncrona) → predeterminado.

  • process_mail() lo aplica por sí mismo: si la estructura no pasa un "lang" explícito, lo obtiene del primer destinatario con language_pref_for_email(). Un "lang" pasado por quien llama manda siempre.
  • Mailer::setLang($code) fija el idioma de composición: los códigos {_…} de la plantilla, el asunto cuando es un código del diccionario, las cadenas de PHPMailer; null vuelve a FF_LOCALE. Los códigos de la plantilla los traduce loadTemplateFile() (vendor/wolfgan/mailer/Mailer.php) antes de pasar el texto a ffTemplate, que por sí solo usaría siempre FF_LOCALE: hasta la 3.0.3 pasaba esto, y desde un cron el cuerpo salía en el idioma predeterminado aun con setLang(). ⚠️ Mailer es un singleton: quien fija el idioma debe volver a fijarlo en cada envío, si no el envío siguiente lo hereda.
  • El asunto se busca en el diccionario solo si es un código, es decir, sin espacios. Un asunto ya escrito se queda como está: buscarlo hacía que se insertara como marcador de posición en ff_international, y con un código o una fecha dentro era una fila nueva en cada envío. Quien quiera el asunto traducido lo compone en el idioma del destinatario, como hace hook.php para la activación y la recuperación (svc_mail_act_subject, svc_mail_rec_subject, idioma desde language_pref_for_email(), la misma que usa el Notifier).
  • Notifier agrupa los destinatarios email por idioma y hace un envío por grupo (ver §3).

La preferencia se escribe solo con una elección explícita desde el selector de idioma (?lang=), ver 12 — Caché, §Multilingüe.

La regla de las imágenes

El logo en los emails es siempre un PNG. Nunca un SVG: los clientes de correo no lo renderizan.

Sobre cómo llega, en cambio, decide el relay. Históricamente el logo se adjuntaba y se referenciaba con cid:, porque los clientes bloquean las imágenes remotas y un logo por URL, para una parte de los destinatarios, es ningún logo. Pero ciertos relays (JoeSMTP, Aruba) rechazan el mensaje entero si contiene una parte adjunta — 550 … Attachments are not supported — y un logo que no se ve es de todos modos mejor que un email que no sale.

Por eso Mailer por defecto reescribe las referencias cid:<archivo> como URL absolutas hacia WWW_LINK_ABSOLUTE: esos archivos el sitio ya los sirve, están en themes/<tema>/contents/email/<plantilla>/images/. Donde el relay acepta adjuntos y se prefiere el logo garantizado, basta define("MAILER_EMBED_IMAGES", true) en config.remote.php.

La reserva es prudente: si la URL absoluta no se puede obtener — archivo fuera de la docroot, WWW_LINK_ABSOLUTE no definida para ese host — la imagen sigue incrustada como antes.

Los adjuntos

Misma razón, mismo tratamiento: por defecto Mailer no adjunta los archivos, sino que añade al final del cuerpo (HTML y texto) la lista de enlaces. Los uploads pasan por CM_SHOWFILES, así en un email que circula fuera del sitio no aparece la ruta verdadera de la carpeta; los archivos que están junto a la plantilla (.../attach/) van por URL directa.

Si la dirección no se puede obtener el archivo sigue adjunto de verdad: quitar el adjunto sin dar su dirección significaría enviar un email incompleto. Para volver a los adjuntos verdaderos: define("MAILER_EMBED_ATTACHMENTS", true).

Otras reglas que se aprenden enviando

  • El remitente debe ser del dominio que envía (SPF/DKIM). Un From: con el dominio del destinatario es la forma más rápida de acabar en spam.
  • Un registro de envíos es un antiduplicados, no un histórico. Antes de enviar una comunicación automática se verifica si ya se ha enviado para esa clave (destinatario, tipo, periodo); la restricción única en la tabla es más fiable que un recuento. Por eso el registro no se poda (ver 05 §6).
  • Los emails de sistema del módulo auth (activación, recuperación de contraseña) salen por su cuenta: si el proyecto enruta todo lo demás por un relay propio, esos dos hay que considerarlos aparte.
  • Vista previa antes del envío: contents/emailpreviewer/ + /srv/email-preview sirven para mirar el mensaje renderizado sin enviarlo. Usarlos es mucho más rápido que enviarse emails de prueba.

La biblioteca: PHPMailer 7 con los nombres de la 5.2

library/phpmailer/ es PHPMailer 7.1.1 (src/, espacio de nombres PHPMailer\PHPMailer). Hasta la 3.1.0 era la 5.2.14, de 2015, con los fallos conocidos del transporte mail() (CVE-2016-10033, CVE-2016-10045) y sin soporte para PHP 8. La plataforma sigue cargándola con las rutas y las clases de entonces — autoload.php, cm/autoload.php, library/gallery/process/mail.php y vendor/wolfgan/mailer/Mailer.php hacen require de class.phpmailer.php, class.smtp.php… y new phpmailer() — y lo mismo puede hacer un sitio: class.phpmailer.php, class.smtp.php y class.pop3.php son adaptadores que definen PHPMailer, phpmailerException, SMTP y POP3 como alias de las clases de la 7. Las propiedades y los métodos que usa la plataforma están todos; setLanguage() en la 7 es estático, y llamarlo sobre una instancia funciona como antes. Ya no están el OAuth de la 5.2 (PHPMailerOAuth, PHPMailerOAuthGoogle), EasyPeasyICS ni NTLM: sus archivos quedan vacíos porque los cargadores los requieren. El código nuevo puede usar directamente \PHPMailer\PHPMailer\PHPMailer.

La abstracción Mailer

Mailer::getInstance() ofrece una API de objetos (setTitle, setMessage, addAddress, addAttach, addUsers, addGroups, addActions, renderPreview, send) con servicios sustituibles (email_localhost, email_sparkpost) y carga de la plantilla desde el tema. Es la vía para enviar a usuarios y grupos del CMS en lugar de a direcciones. En el repo se usa sobre todo a través de Notifier.

3. Notificaciones in-app

vendor/hcore/notifier/Notifier.php es un motor de notificación multicanal y multidestinatario. Es la única copia: el CMS lo carga desde vendor/ mediante COMPOSER_PATH (las viejas copias en library/classes/ y library/gallery/classes/ se han eliminado porque nadie las cargaba).

Notifier::getInstance(array("sms", "email"))
    ->send($message, $users, $groups, $title, $type, $media, $actions, $schedule, $expire, $referer);

Qué sabe hacer, mirando los métodos:

MétodoCapacidad
setUsers() / setGroups()destinatarios por usuario o por grupo del CMS
setMessage($msg, $title, $type, $schedule, $expire, $media, $actions, $referer)texto, tipo, programación, caducidad, media adjunto, acciones (botones)
setSchedule() / setExpire() / setTimer()cuándo aparece y cuándo deja de aparecer
read() / update()lectura y actualización del estado
delivered()marca como entregadas
response($keys)payload para el front-end
sendMail()el canal email de la notificación: un envío por idioma de los destinatarios, con Mailer::setLang()
setDomain(), setPage(), setUrl(), setVisitor()contextualiza la notificación

El front-end las recoge desde el bus de servicios: /srv/request con la entrada notify llama a Notifier::response(), y notifyDelivered llama a Notifier::delivered() (ver 03 §3). Es el mecanismo que permite a una página en caché mostrar igualmente las notificaciones del usuario.

La UI está en vendor/hcore/notifier/widgets/notifier/. La gestión desde el backend es /restricted/notify.

4. Push y SMS

Son drivers del Notifier, en vendor/hcore/notifier/services/:

ArchivoCanalServicio (área Servicios)Campos
push_onesignal.phppush vía OneSignalnotification.onesignalcode (App ID), api_key (clave REST), safari
sms_joesmtp.phpSMS vía JoeSMTP (/api/1.0/sms-send)sms.joesmtphost (vacío = joesmtp.it), client_id, client_secret, from
sms_twilio.phpSMS vía Twilio (REST)sms.twiliosid, token, from

Las credenciales se introducen desde el área Servicios del backend (o desde el asistente, paso Servicios): son filas en cm_mod_security_domains_fields. Para el push siguen valiendo, como reserva, las constantes NOTIFY_ONESIGNAL_APP_ID / NOTIFY_ONESIGNAL_API_KEY. Ver 10.

Notifier::getInstance("sms")->send("Tu código es 123456", "+393331234567");
Notifier::getInstance("push")->send(array(
    "title" => "Clase confirmada", "message" => "Te esperamos a las 18", "actions" => array("/area-utente")
), array($ID_user));
  • Destinatarios. Un teléfono se reconoce solo con el prefijo +: un número desnudo se tomaría por un ID de usuario. Normalizarlo antes con Notifier::normalizeTel($tel) (E.164, +39 si falta el prefijo). El push se dirige por ID de usuario del CMS; los grupos no están soportados.
  • Qué proveedor SMS. Sin servicio explícito se usa el primero configurado: JoeSMTP, luego Twilio. Para forzar uno: Notifier::getInstance(array("sms" => "twilio")).
  • Idioma. Para SMS y push el texto lo compone quien llama, y nadie lo traduce: el agrupamiento por idioma vale solo para el canal email (§2). Si el mensaje sale de un cron, obtener el idioma con language_pref_for_user($ID_user) antes de componer el texto.
  • Resultado. send() devuelve el resultado del driver: status "0" si ha salido, si no status y error, y el fallo acaba en el log notifier_error. JoeSMTP distingue sent de pending: en el segundo caso el mensaje está en su cola y lo reintenta su cron.
  • Push, lado navegador. Con enable y code el servicio notification.onesignal inyecta el Web SDK v16 en cada página y sirve desde la raíz el service worker /OneSignalSDKWorker.js. El usuario conectado se vincula a su suscripción con OneSignal.login(<ID usuario>): el ID lo pide el navegador a /OneSignalIdentity (Cache-Control: no-store), nunca escrito en el HTML, que puede acabar en la caché compartida. Al salir sigue OneSignal.logout(). Prompt, campana y textos se configuran desde el panel de OneSignal (Settings → Web → Typical Site); el idioma de la página pasa con User.setLanguage.
  • Push, envío. POST https://api.onesignal.com/notifications con Authorization: Key <api_key>, destinatarios en include_aliases.external_id. Un envío a usuarios que nunca se han suscrito funciona igualmente (ningún error, id vacío): no es una avería.

5. Añadir un canal

El patrón de los servicios de Notifier y Mailer es el mismo: un archivo por canal, que declara una const TYPE e implementa el envío. Un driver push/SMS del Notifier expone isConfigured() (estático) y send($payload), que recibe Notifier::getPayload() y devuelve array("status" => "0" | código, "error" => …). Para un proveedor nuevo:

  1. copiar el driver más cercano (sms_joesmtp.php para una API con token, sms_twilio.php para una con Basic auth, email_localhost.php para SMTP) y, si es un SMS, añadirlo a la lista de controller_sms(): vgCommon::loadControllers registra un solo driver por tipo como predeterminado, la elección la hace el Notifier;
  2. leer las credenciales desde el área Servicios con Notifier::serviceConfig("<servicio>"), nunca fijarlas en el archivo; para las llamadas usar Notifier::http(), que verifica el certificado;
  3. distinguir de forma explícita fallido de aceptado: casi todos los proveedores responden 202 y entregan después;
  4. si el proveedor expone webhooks de estado, engancharlos como endpoint /srv/<proveedor>/webhook — patrón, secret e idempotencia en 03 §2. Es la única forma de saber si un mensaje ha llegado de verdad;
  5. si el proveedor lo permite, pasar la URL de callback por mensaje en lugar de configurarla en el panel.

Correlación. En el momento del envío, pasar al proveedor una referencia propia (X-Entity-Ref-ID, tag, correlation_id del tipo entidad_x|detalle_y) y leerla en el webhook. Sin ella, cuando llegan los informes no se sabe a qué pertenecen, y no se reconstruye a posteriori.

6. Trampas ya pagadas

  • 550 … Attachments are not supported no habla de tamaños ni de MIME: ese relay rechaza cualquier parte adjunta — imágenes inline cid: incluidas — y rechaza el mensaje entero, que por tanto no sale en absoluto. Cómo lo trata Mailer: §2, «La regla de las imágenes».
  • Las estadísticas de un canal no se actualizan porque la ruta de ese canal escribe en una tabla distinta de la que lee el panel. Antes de culpar al webhook, verificar qué tabla lee la pantalla.
  • Porcentajes por encima del 100%: los contadores se incrementan con cada evento, y los proveedores repiten los eventos. El incremento debe ocurrir solo cuando el flag por destinatario pasa de 0→1 (AND flag = 0 en el WHERE + control de affectedRows()).
  • Emoji truncados o mensaje vacío: las tablas históricas del CMS son utf8mb3. Las tablas nuevas que contienen texto libre deben crearse utf8mb4, y la conexión debe configurarse en consecuencia.
  • Un From: sin remitente aprobado en el proveedor hace fallar el envío con un error que no habla de remitentes. Verificarlo lo primero.
  • Notifier::send() y Mailer::send() no devuelven un array de resultado. Con un solo servicio activo devuelven el bool de PHPMailer si el envío tiene éxito y la cadena del mensaje si falla (Notifier::getResult() y Mailer::getResult() remiten a vgCommon::isError()); el array llega solo con varios servicios. Leer $esito["error"] sin is_array() era un warning en PHP 7 y es un fatal desde PHP 8 — así una avería de correo se presenta como 500 en lugar de como mensaje. La forma correcta:
    $esito = Notifier::getInstance("email")->send($params);
    $errore = (is_array($esito) ? ($esito["error"] ?? null) : $esito);

    El mensaje técnico del envío fallido acaba de todos modos en el log error_critical, escrito por vgCommon::isError(): es ahí donde se busca la razón verdadera.