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
| Canal | Motor | Estado en el repo |
|---|---|---|
| Email transaccional | process_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-app | Notifier (vendor/hcore/notifier/) + sección de backend /restricted/notify | presente, con widget y applet |
| Push navegador/app | driver push_onesignal + servicio notification.onesignal | listo, requiere App ID y clave REST |
| SMS | drivers sms_joesmtp / sms_twilio + servicios sms.joesmtp / sms.twilio | listo, requiere credenciales |
| Segundo factor en el login | Auth::login + canal email o SMS del Notifier | apagado por defecto (AUTH_2FA), ver 08 |
| Vista previa de emails | contents/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:
| Helper | Cuá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 conlanguage_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;nullvuelve aFF_LOCALE. Los códigos de la plantilla los traduceloadTemplateFile()(vendor/wolfgan/mailer/Mailer.php) antes de pasar el texto affTemplate, que por sí solo usaría siempreFF_LOCALE: hasta la 3.0.3 pasaba esto, y desde un cron el cuerpo salía en el idioma predeterminado aun consetLang(). ⚠️Maileres 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 hacehook.phppara la activación y la recuperación (svc_mail_act_subject,svc_mail_rec_subject, idioma desdelanguage_pref_for_email(), la misma que usa elNotifier). Notifieragrupa 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-previewsirven 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étodo | Capacidad |
|---|---|
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/:
| Archivo | Canal | Servicio (área Servicios) | Campos |
|---|---|---|---|
push_onesignal.php | push vía OneSignal | notification.onesignal | code (App ID), api_key (clave REST), safari |
sms_joesmtp.php | SMS vía JoeSMTP (/api/1.0/sms-send) | sms.joesmtp | host (vacío = joesmtp.it), client_id, client_secret, from |
sms_twilio.php | SMS vía Twilio (REST) | sms.twilio | sid, 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 conNotifier::normalizeTel($tel)(E.164,+39si 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 nostatusyerror, y el fallo acaba en el lognotifier_error. JoeSMTP distinguesentdepending: en el segundo caso el mensaje está en su cola y lo reintenta su cron. - Push, lado navegador. Con
enableycodeel servicionotification.onesignalinyecta 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 conOneSignal.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 sigueOneSignal.logout(). Prompt, campana y textos se configuran desde el panel de OneSignal (Settings → Web → Typical Site); el idioma de la página pasa conUser.setLanguage. - Push, envío.
POST https://api.onesignal.com/notificationsconAuthorization: Key <api_key>, destinatarios eninclude_aliases.external_id. Un envío a usuarios que nunca se han suscrito funciona igualmente (ningún error,idvací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:
- copiar el driver más cercano (
sms_joesmtp.phppara una API con token,sms_twilio.phppara una con Basic auth,email_localhost.phppara SMTP) y, si es un SMS, añadirlo a la lista decontroller_sms():vgCommon::loadControllersregistra un solo driver por tipo como predeterminado, la elección la hace elNotifier; - leer las credenciales desde el área Servicios con
Notifier::serviceConfig("<servicio>"), nunca fijarlas en el archivo; para las llamadas usarNotifier::http(), que verifica el certificado; - distinguir de forma explícita fallido de aceptado: casi todos los proveedores responden 202 y entregan después;
- 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; - 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_iddel tipoentidad_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 supportedno habla de tamaños ni de MIME: ese relay rechaza cualquier parte adjunta — imágenes inlinecid:incluidas — y rechaza el mensaje entero, que por tanto no sale en absoluto. Cómo lo trataMailer: §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 = 0en elWHERE+ control deaffectedRows()). - Emoji truncados o mensaje vacío: las tablas históricas del CMS son
utf8mb3. Las tablas nuevas que contienen texto libre deben crearseutf8mb4, 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()yMailer::send()no devuelven un array de resultado. Con un solo servicio activo devuelven elboolde PHPMailer si el envío tiene éxito y la cadena del mensaje si falla (Notifier::getResult()yMailer::getResult()remiten avgCommon::isError()); el array llega solo con varios servicios. Leer$esito["error"]sinis_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 porvgCommon::isError(): es ahí donde se busca la razón verdadera.