Email, notifications, SMS and push
The CMS can send: transactional emails with templates and attachments, in-app notifications, SMS and push through providers. Not everything is wired to the same level: this page says what's ready, what's present-but-to-configure and what's upstream scaffolding.
1. Overview
| Channel | Engine | Status in the repo |
|---|---|---|
| Transactional email | process_mail() + PHPMailer (SMTP) | in production: registration, activation, password recovery |
| Email (service abstraction) | Mailer (vendor/wolfgan/mailer/) | present; services email_localhost (SMTP) and email_sparkpost |
| In-app notifications | Notifier (vendor/hcore/notifier/) + backend section /restricted/notify | present, with widget and applet |
| Browser/app push | push_onesignal driver + notification.onesignal service | ready, needs App ID and REST key |
| SMS | sms_joesmtp / sms_twilio drivers + sms.joesmtp / sms.twilio services | ready, needs credentials |
| Second factor at login | Auth::login + the Notifier's email or SMS channel | off by default (AUTH_2FA), see 08 |
| Email preview | contents/emailpreviewer/, /srv/email-preview (rule in modules/cms-common) | present |
2. Transactional email
Configuration
The installer writes into 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", "");
They're read by vendor/wolfgan/mailer/services/email_localhost.php (and the sparkpost equivalent). The wizard sends a test email during installation, with a standalone SMTP client (SSL 465 / STARTTLS 587 / plain): mail is verified before finishing, not when the first user signs up.
Sending
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 builds a structure with theme, domain, language and SMTP parameters, then resolves the template and sends. Templates live in themes/<theme>/contents/email/ — in the repo, auth/activation_code.html, auth/recover_code.html and auth/account_code.html (the 2FA code), with images in email/images/. Their texts are dictionary codes (svc_mail_*), so the email goes out in the composition language (below); up to 3.0.3 they were written in Italian inside the file.
Which language an email goes out in
The recipient's language, not the request's. FF_LOCALE is fine for synchronous sends (the recipient is whoever just clicked), but in a cron or an async job — reminders, deadlines, waitlists, renewals — there's no request, and FF_LOCALE would be the default for everyone. That's why the language preference lives on the profile (access_users.locale / access_users.ID_lang, see 07 §3) and is read by the helpers in library/gallery/common/language_preference.php:
| Helper | When |
|---|---|
language_pref_for_user($ID_user) | you have the ID: emails, notifications, PDFs, SMS generated by cron/jobs |
language_pref_for_email($email) | you only have the address; returns null if it's unknown or if several accounts with that address have different preferences |
Order: recipient's profile → request language (only if synchronous) → default.
process_mail()applies it by itself: if the structure doesn't pass an explicit"lang", it derives it from the first recipient withlanguage_pref_for_email(). A"lang"passed by the caller always wins.Mailer::setLang($code)sets the composition language: the template's{_…}codes, the subject when it is a dictionary code, the PHPMailer strings;nullgoes back toFF_LOCALE. The template codes are translated byloadTemplateFile()(vendor/wolfgan/mailer/Mailer.php) before the text reachesffTemplate, which on its own would always useFF_LOCALE: up to 3.0.3 that is what happened, and from a cron job the body went out in the default language even withsetLang(). ⚠️Maileris a singleton: whoever sets the language must reset it on every send, otherwise the next send inherits it.- The subject is looked up in the dictionary only when it is a code, that is without spaces. A subject that is already written stays as it is: looking it up made it get inserted as a placeholder in
ff_international, and with a code or a date inside it was a new row on every send. Whoever wants a translated subject builds it in the recipient's language, likehook.phpdoes for activation and recovery (svc_mail_act_subject,svc_mail_rec_subject, language fromlanguage_pref_for_email(), the same one theNotifieruses). Notifiergroups email recipients by language and makes one send per group (see §3).
The preference is written only by an explicit choice from the language switcher (?lang=), see 12 — Cache, §Multilingual.
The rule on images
The logo in emails is always a PNG. Never an SVG: mail clients don't render it.
How it arrives, on the other hand, is up to the relay. Historically the logo was attached and referenced with cid:, because clients block remote images and a logo by URL, for some recipients, is no logo. But some relays (JoeSMTP, Aruba) reject the whole message if it contains an attachment part — 550 … Attachments are not supported — and an invisible logo is still better than an email that doesn't go out.
That's why by default Mailer rewrites cid:<file> references as absolute URLs to WWW_LINK_ABSOLUTE: the site already serves those files, they live in themes/<theme>/contents/email/<template>/images/. Where the relay accepts attachments and you prefer the guaranteed logo, just define("MAILER_EMBED_IMAGES", true) in config.remote.php.
The fallback is cautious: if the absolute URL can't be derived — file outside the docroot, WWW_LINK_ABSOLUTE not defined for that host — the image stays embedded as before.
Attachments
Same reason, same treatment: by default Mailer doesn't attach files, but appends a list of links to the body (HTML and text). Uploads go through CM_SHOWFILES, so an email travelling outside the site doesn't show the real folder path; files sitting next to the template (.../attach/) go by direct URL.
If the address can't be derived the file stays really attached: removing the attachment without giving its address would mean sending a truncated email. To go back to real attachments: define("MAILER_EMBED_ATTACHMENTS", true).
Other rules you learn by sending
- The sender must belong to the sending domain (SPF/DKIM). A
From:with the recipient's domain is the fastest way into spam. - A send log is an anti-duplicate, not history. Before sending an automatic communication, check whether it was already sent for that
(recipient, type, period)key; a unique constraint on the table is more reliable than a count. That's why the log isn't pruned (see 05 §6). - The
authmodule's system emails (activation, password recovery) go out on their own: if the project routes everything else through its own relay, those two must be considered separately. - Preview before sending:
contents/emailpreviewer/+/srv/email-previewlet you look at the rendered message without sending it. Using them is much faster than emailing yourself tests.
The library: PHPMailer 7 with the 5.2 names
library/phpmailer/ is PHPMailer 7.1.1 (src/, namespace PHPMailer\PHPMailer). Up to 3.1.0 it was 5.2.14, from 2015, with the known flaws of the mail() transport (CVE-2016-10033, CVE-2016-10045) and no PHP 8 support. The platform keeps loading it with the paths and classes of back then — autoload.php, cm/autoload.php, library/gallery/process/mail.php and vendor/wolfgan/mailer/Mailer.php require class.phpmailer.php, class.smtp.php… and do new phpmailer() — and a site can do the same: class.phpmailer.php, class.smtp.php and class.pop3.php are adapters that define PHPMailer, phpmailerException, SMTP and POP3 as aliases of the 7 classes. All the properties and methods the platform uses are there; setLanguage() is static in 7, and calling it on an instance works as before. The 5.2 OAuth (PHPMailerOAuth, PHPMailerOAuthGoogle), EasyPeasyICS and NTLM are gone: their files stay empty because the loaders require them. New code can use \PHPMailer\PHPMailer\PHPMailer directly.
The Mailer abstraction
Mailer::getInstance() offers an object API (setTitle, setMessage, addAddress, addAttach, addUsers, addGroups, addActions, renderPreview, send) with replaceable services (email_localhost, email_sparkpost) and template loading from the theme. It's the way to send to CMS users and groups instead of addresses. In the repo it's used mainly through Notifier.
3. In-app notifications
vendor/hcore/notifier/Notifier.php is a multi-channel, multi-recipient notification engine. It's the only copy: the CMS loads it from vendor/ via COMPOSER_PATH (the old copies in library/classes/ and library/gallery/classes/ were removed because nothing loaded them).
Notifier::getInstance(array("sms", "email"))
->send($message, $users, $groups, $title, $type, $media, $actions, $schedule, $expire, $referer);
What it can do, looking at the methods:
| Method | Capability |
|---|---|
setUsers() / setGroups() | recipients by user or by CMS group |
setMessage($msg, $title, $type, $schedule, $expire, $media, $actions, $referer) | text, type, scheduling, expiry, attached media, actions (buttons) |
setSchedule() / setExpire() / setTimer() | when it appears and when it stops appearing |
read() / update() | reading and updating state |
delivered() | marks as delivered |
response($keys) | payload for the front end |
sendMail() | the notification's email channel: one send per recipient language, with Mailer::setLang() |
setDomain(), setPage(), setUrl(), setVisitor() | puts the notification in context |
The front end collects them from the service bus: /srv/request with the notify entry calls Notifier::response(), and notifyDelivered calls Notifier::delivered() (see 03 §3). It's the mechanism that lets a cached page still show the user's notifications.
The UI is in vendor/hcore/notifier/widgets/notifier/. Backend management is at /restricted/notify.
4. Push and SMS
They're drivers of the Notifier, in vendor/hcore/notifier/services/:
| File | Channel | Service (Services area) | Fields |
|---|---|---|---|
push_onesignal.php | push via OneSignal | notification.onesignal | code (App ID), api_key (REST key), safari |
sms_joesmtp.php | SMS via JoeSMTP (/api/1.0/sms-send) | sms.joesmtp | host (empty = joesmtp.it), client_id, client_secret, from |
sms_twilio.php | SMS via Twilio (REST) | sms.twilio | sid, token, from |
Credentials are entered from the backend's Services area (or from the wizard, Services step): they're rows in cm_mod_security_domains_fields. For push, the constants NOTIFY_ONESIGNAL_APP_ID / NOTIFY_ONESIGNAL_API_KEY still apply as a fallback. See 10.
Notifier::getInstance("sms")->send("Your code is 123456", "+393331234567");
Notifier::getInstance("push")->send(array(
"title" => "Lesson confirmed", "message" => "See you at 6pm", "actions" => array("/area-utente")
), array($ID_user));
- Recipients. A phone number is recognised only with the
+prefix: a bare number would be taken for a user ID. Normalise it first withNotifier::normalizeTel($tel)(E.164,+39if the prefix is missing). Push is addressed by CMS user ID; groups aren't supported. - Which SMS provider. Without an explicit service the first configured one is used: JoeSMTP, then Twilio. To force one:
Notifier::getInstance(array("sms" => "twilio")). - Language. For SMS and push the caller composes the text, and nobody translates it: grouping by language only applies to the email channel (§2). If the message starts from a cron, derive the language with
language_pref_for_user($ID_user)before composing the text. - Outcome.
send()returns the driver's result:status"0"if it went out, otherwisestatusanderror, and the failure lands in thenotifier_errorlog. JoeSMTP distinguishessentfrompending: in the second case the message is queued on their side and their cron retries it. - Push, browser side. With
enableandcode, thenotification.onesignalservice injects Web SDK v16 into every page and serves the/OneSignalSDKWorker.jsservice worker from the root. The logged-in user is linked to their subscription withOneSignal.login(<user ID>): the browser asks/OneSignalIdentityfor the ID (Cache-Control: no-store), never written into the HTML, which may end up in the shared cache. On logout,OneSignal.logout()follows. Prompt, bell and texts are configured from the OneSignal dashboard (Settings → Web → Typical Site); the page language is passed withUser.setLanguage. - Push, sending.
POST https://api.onesignal.com/notificationswithAuthorization: Key <api_key>, recipients ininclude_aliases.external_id. A send to users who never subscribed still succeeds (no error, emptyid): it's not a fault.
5. Adding a channel
The service pattern of Notifier and Mailer is the same: one file per channel, declaring a const TYPE and implementing the send. A Notifier push/SMS driver exposes isConfigured() (static) and send($payload), which receives Notifier::getPayload() and returns array("status" => "0" | code, "error" => …). For a new provider:
- copy the closest driver (
sms_joesmtp.phpfor an API with a token,sms_twilio.phpfor one with Basic auth,email_localhost.phpfor SMTP) and, if it's an SMS, add it to the list incontroller_sms():vgCommon::loadControllersregisters only one driver per type as default, theNotifiermakes the choice; - read credentials from the Services area with
Notifier::serviceConfig("<service>"), never hard-wire them in the file; for calls useNotifier::http(), which verifies the certificate; - explicitly distinguish failed from accepted: almost all providers answer 202 and deliver later;
- if the provider exposes status webhooks, hook them up as a
/srv/<provider>/webhookendpoint — pattern, secret and idempotency in 03 §2. It's the only way to know whether a message really arrived; - if the provider allows it, pass the callback URL per message instead of configuring it in the dashboard.
Correlation. When sending, pass the provider a reference of your own (
X-Entity-Ref-ID,tag,correlation_idlikeentity_x|detail_y) and read it in the webhook. Without it, when the reports arrive you don't know what they belong to, and you can't reconstruct it afterwards.
6. Pitfalls already paid for
550 … Attachments are not supportedisn't about size or MIME: that relay rejects any attachment part — inlinecid:images included — and rejects the whole message, which therefore doesn't go out at all. HowMailerhandles it: §2, "The rule on images".- A channel's statistics don't update because that channel's path writes to a different table from the one the dashboard reads. Before blaming the webhook, check which table the screen reads.
- Percentages over 100%: counters are incremented on every event, and providers repeat events. The increment must happen only when the per-recipient flag transitions 0→1 (
AND flag = 0in theWHERE+ checkingaffectedRows()). - Truncated emoji or empty message: the CMS's historical tables are
utf8mb3. New tables holding free text must be createdutf8mb4, and the connection set accordingly. - A
From:without an approved sender at the provider makes the send fail with an error that doesn't mention senders. Check it first. Notifier::send()andMailer::send()don't return an outcome array. With a single active service they return PHPMailer'sboolif the send succeeds and the message string if it fails (Notifier::getResult()andMailer::getResult()defer tovgCommon::isError()); the array only comes with several services. Reading$esito["error"]withoutis_array()was a warning in PHP 7 and is a fatal error from PHP 8 — so a mail failure shows up as a 500 instead of a message. The right form:$esito = Notifier::getInstance("email")->send($params); $errore = (is_array($esito) ? ($esito["error"] ?? null) : $esito);The technical message of the failed send still lands in the
error_criticallog, written byvgCommon::isError(): that's where to look for the real reason.