Email

CMS Builder’s email features span three menus. Admin Menu > Email Settings controls how mail is sent (from addresses, sending method, and logging mode). Email Templates holds reusable message templates used by the CMS and plugins. Outgoing Mail is a log of sent and queued messages. Outgoing Mail and Email Templates appear as submenus of Email Settings while it is selected, and Email Templates is also always available under CMS Setup > Email Templates.

All mail sent through the sendMessage() function will read its configuration from these settings.

Email Settings

Admin Menu > Email Settings configures the addresses, sending method, and logging behaviour for outgoing mail.

Email Addresses

Admin / From Email

Default “From” address for system emails such as password reminders and notifications. Also available as the #settings.adminEmail# placeholder in Email Templates. Must be a valid email address.

Developer Email

Default “To” address for PHP error notifications and task log errors. Also available as the #settings.developerEmail# placeholder in Email Templates. Multiple addresses can be comma-separated.

The checkbox below this field enables an email notification (using the CMS-ERRORLOG-ALERT template) when PHP errors are detected in the error log. Error notifications are sent at most once an hour.

Outgoing Mail Settings

Outgoing Mail

Controls whether outgoing messages are logged under the Outgoing Mail menu:

Send Only — send mail without keeping a copy (default)
Send & Log — send mail and save copies under Outgoing Mail
Log Only — log messages but don’t send them (debug mode)

While Log Only is selected, a warning is shown on this page and the Email Settings entry in the Admin Menu is highlighted, since no mail leaves the server in this mode.

How to send mail

Selects the sending method:

Use PHP’s built-in mail() function (default)
SMTP Server - Unsecured connection
SMTP Server - Secured connection using SSL
SMTP Server - Secured connection using TLS
Google Account (OAuth Authentication)

Selecting an SMTP or OAuth method reveals the corresponding fields below.

SMTP settings

Shown for the three SMTP methods.

SMTP Hostname & Port

The mail server hostname and port. The server defaults from php.ini (SMTP and smtp_port) are shown beside the fields and used as fallbacks when left blank.

Your mail host supplies these values. Most hosts use port 465 for SSL connections and 587 for TLS; pick the sending method to match the port your host specifies.

SMTP Username

Username for SMTP authentication. Most hosts use the full email address as the username.

SMTP Password

Password for SMTP authentication. Displayed masked, revealed while the field has focus.

On installations configured to load settings from a .env file, the SMTP credential fields are replaced by a note showing which file to edit.

OAuth settings

Shown for the Google Account method. Step-by-step Google Cloud setup instructions are available inline on the page (“Show Google setup instructions”), covering project creation, the OAuth consent screen, and creating an OAuth Client ID with the callback URL the page provides.

OAuth Username: The Google Workspace or Gmail address to send as.
OAuth Client ID: Client ID from the OAuth credentials created in Google Cloud.
OAuth Client Secret: Client secret from the same OAuth credentials.
OAuth Refresh Token: Read-only. The Save Settings & Request button saves the current form, then redirects through the provider’s authorization screens to obtain a refresh token. Once a token is stored, its details (issuing account and issuer) are displayed below the field.

Send Test Email

The bottom of the page has From, To, Subject, and Message fields (plain text only) for sending a test message. From defaults to the Admin / From Email and To defaults to the Developer Email. Send Test Email opens a new window showing the settings used and the full mail server debug output, so connection and authentication problems are visible immediately.

Test messages use the settings currently entered in the form, whether saved or not, and are always sent and logged regardless of the Outgoing Mail mode. The page also links to third-party services (mxtoolbox.com, mail-tester.com) for checking deliverability, SPF, DKIM, DMARC, and blacklists.

Email Templates

Email Templates are reusable messages stored in the _email_templates section. Each template defines the addresses, subject, and HTML body for one type of email the CMS or a plugin sends, so the wording can be edited in the CMS Admin without touching code. The menu appears under CMS Setup > Email Templates and as a submenu of Admin Menu > Email Settings.

The list page shows each template’s ID, description, and subject alongside its From/To addresses, and supports the standard list search. Default templates are created automatically when the menu is opened or when a message needs one, both the CMS’s own templates and any registered by plugins. Deleting a default template causes it to be recreated with its original content the next time it is needed, so edits should modify templates rather than remove them.

The CMS ships with these templates:

CMS-PASSWORD-RESET: Sent to users when they request to reset their password via the “Forgot your password?” link on the login page. The message goes to the email address on the user’s account, from the Admin / From Email address, and contains a #resetUrl# reset link that stays valid for at least 24 hours (changing the password invalidates outstanding links). If the message can’t be sent, the error is displayed on screen at request time. A French translation, CMS-PASSWORD-RESET-FR, is also included.
CMS-BGTASK-ERROR: Sent to the developer email when a scheduled task fails.
CMS-ERRORLOG-ALERT: Sent to the developer email when a PHP error or warning is reported, if enabled under Email Settings.

Template fields

Template ID: Unique identifier that code uses to load the template. Adding a -XX language code suffix creates a translation: when the program language is set, the CMS looks for the suffixed ID first (for example CMS-PASSWORD-RESET-FR when the language is fr), then falls back to the base ID.
Description: Notes on what the template is used for.
From / Reply-To / To / CC / BCC: Email address fields. These support placeholders, so a template can be addressed with values such as #settings.adminEmail# or #user.email# that are filled in at send time.
Subject: The email subject. Supports placeholders.
Message HTML: The email body, edited with the WYSIWYG editor. Supports placeholders. When the message is sent, the body is wrapped in a minimal HTML document (doctype, head, and title from the subject) unless the sending code disables that.
Attachments: Upload field for files attached to every message sent from this template.
Placeholders: A reference list of the placeholders available to this template. It is updated automatically each time the template is used to send a message, so it reflects the placeholders the sending code actually supplies. The field is informational and shouldn’t be modified.

Placeholders

Placeholders use #name# syntax and are replaced in the address fields, subject, and message body when a message is sent. Each template receives custom placeholders from the code that sends it (for example #user.email# and #resetUrl# for password resets), plus these global placeholders that are always available:

#server.http_host#: The website’s hostname.
#server.remote_addr#: The IP address of the visitor who triggered the email.
#settings.adminEmail#: The Admin / From Email from Email Settings.
#settings.developerEmail#: The Developer Email from Email Settings.
#settings.adminUrl#: The URL of the CMS Admin.
#settings.programName#: The program name from General Settings.

Sending template emails from code

Plugins and custom code load a template with emailTemplate_loadFromDB(), which returns the headers and body with placeholders replaced, ready to pass to sendMessage():

$emailHeaders = emailTemplate_loadFromDB([
    'template_id'  => 'MY-TEMPLATE-ID',
    'placeholders' => [
        'user.email'    => $userEmail,
        'user.fullname' => $userFullname,
    ],
]);
$mailErrors = sendMessage($emailHeaders);
if ($mailErrors) { die("Mail Error: $mailErrors"); }

The list page’s advanced commands dropdown includes two developer exports: Developers: Export Templates As PHP outputs emailTemplate_addToDB() code for recreating the current templates (the call plugins use to register their defaults), and Developers: Show sendMessage() PHP outputs ready-to-use sending code like the example above for each template.

Individual templates can be linked to directly by ID with ?menu=_email_templates&template_id=MY-TEMPLATE-ID, which redirects to that template’s edit page.

Outgoing Mail

Outgoing Mail is a log of messages sent through sendMessage(), stored in the _outgoing_mail section. It appears as a submenu of Admin Menu > Email Settings while either menu is selected, with the current record count beside the menu name. Messages are logged when the Outgoing Mail mode is Send & Log or Log Only; in Send Only mode nothing is recorded.

A notice at the top of the list shows the current mode with links to Email Settings and Clear Log, which permanently deletes all logged messages. The list shows each message’s date, from, to, and subject, ordered newest first, along with:

Sent

The date and time the message was handed to the mail system. Blank for messages that were logged but not sent (Log Only mode, or messages queued for background sending).

A Sent date means a send was attempted, not that it succeeded; send failures aren’t recorded in this log. To diagnose delivery problems, use Send Test Email on the Email Settings page, which shows the full mail server debug output.

Background Send

Whether the message was queued by sendBackground() instead of sent immediately. sendBackground() writes the message to this log with the flag set and returns without sending; delivering queued messages requires a separate background-mailer script run on a schedule, which the CMS does not include.

Opening a record shows the full message: addresses (including Reply-To, CC, and BCC), subject, the HTML and plain-text bodies, and any extra message headers. There is no resend feature; logged messages are records only.

Documents CMS Builder 3.83