Skip to content
JoeCMS Download 3.1.5
Manual · 06

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

ChannelEngineStatus in the repo
Transactional emailprocess_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 notificationsNotifier (vendor/hcore/notifier/) + backend section /restricted/notifypresent, with widget and applet
Browser/app pushpush_onesignal driver + notification.onesignal serviceready, needs App ID and REST key
SMSsms_joesmtp / sms_twilio drivers + sms.joesmtp / sms.twilio servicesready, needs credentials
Second factor at loginAuth::login + the Notifier's email or SMS channeloff by default (AUTH_2FA), see 08
Email previewcontents/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:

HelperWhen
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 with language_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; null goes back to FF_LOCALE. The template codes are translated by loadTemplateFile() (vendor/wolfgan/mailer/Mailer.php) before the text reaches ffTemplate, which on its own would always use FF_LOCALE: up to 3.0.3 that is what happened, and from a cron job the body went out in the default language even with setLang(). ⚠️ Mailer is 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, like hook.php does for activation and recovery (svc_mail_act_subject, svc_mail_rec_subject, language from language_pref_for_email(), the same one the Notifier uses).
  • Notifier groups 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 auth module'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-preview let 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:

MethodCapability
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/:

FileChannelService (Services area)Fields
push_onesignal.phppush via OneSignalnotification.onesignalcode (App ID), api_key (REST key), safari
sms_joesmtp.phpSMS via JoeSMTP (/api/1.0/sms-send)sms.joesmtphost (empty = joesmtp.it), client_id, client_secret, from
sms_twilio.phpSMS via Twilio (REST)sms.twiliosid, 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 with Notifier::normalizeTel($tel) (E.164, +39 if 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, otherwise status and error, and the failure lands in the notifier_error log. JoeSMTP distinguishes sent from pending: in the second case the message is queued on their side and their cron retries it.
  • Push, browser side. With enable and code, the notification.onesignal service injects Web SDK v16 into every page and serves the /OneSignalSDKWorker.js service worker from the root. The logged-in user is linked to their subscription with OneSignal.login(<user ID>): the browser asks /OneSignalIdentity for 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 with User.setLanguage.
  • Push, sending. POST https://api.onesignal.com/notifications with Authorization: Key <api_key>, recipients in include_aliases.external_id. A send to users who never subscribed still succeeds (no error, empty id): 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:

  1. copy the closest driver (sms_joesmtp.php for an API with a token, sms_twilio.php for one with Basic auth, email_localhost.php for SMTP) and, if it's an SMS, add it to the list in controller_sms(): vgCommon::loadControllers registers only one driver per type as default, the Notifier makes the choice;
  2. read credentials from the Services area with Notifier::serviceConfig("<service>"), never hard-wire them in the file; for calls use Notifier::http(), which verifies the certificate;
  3. explicitly distinguish failed from accepted: almost all providers answer 202 and deliver later;
  4. if the provider exposes status webhooks, hook them up as a /srv/<provider>/webhook endpoint — pattern, secret and idempotency in 03 §2. It's the only way to know whether a message really arrived;
  5. 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_id like entity_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 supported isn't about size or MIME: that relay rejects any attachment part — inline cid: images included — and rejects the whole message, which therefore doesn't go out at all. How Mailer handles 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 = 0 in the WHERE + checking affectedRows()).
  • Truncated emoji or empty message: the CMS's historical tables are utf8mb3. New tables holding free text must be created utf8mb4, 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() and Mailer::send() don't return an outcome array. With a single active service they return PHPMailer's bool if the send succeeds and the message string if it fails (Notifier::getResult() and Mailer::getResult() defer to vgCommon::isError()); the array only comes with several services. Reading $esito["error"] without is_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_critical log, written by vgCommon::isError(): that's where to look for the real reason.