Skip to content

MailTemplate

The MailTemplate component provides mailing capabilities to Cloudrexx.

Info

All mail handling in Cloudrexx should be done using MailTemplate.

Features

Sending e-mails

Either send e-mails from scratch using \Cx\Core\MailTemplate\Model\Entity\Mail:

Example

1
2
3
4
5
6
7
$mail = new \Cx\Core\MailTemplate\Model\Entity\Mail();
$mail->setFrom($senderEmail, $senderName);
$mail->addAddress($toEmailAddress);
$mail->Subject = $subject;
$mail->Body = $htmlBody;
$mail->AltBody = $plaintextBody;
$mail->send();

or by using the e-mail templating capabilities either with (set key) or without a template:

Example

1
2
3
4
5
6
$options = [
    'to'      => 'info@example.org',
    'subject' => 'Hello World',
    'message' => 'This is a plaintext message',
];
\Cx\Core\MailTemplate\Controller\MailTemplate::send($options);

The full list of $options that can be passed to send() is as follows:

Key Description
key The key of any mail template to be used
section The module to initialize for (mandatory when key is set)
sender The sender name
from The sender e-mail address
to The recipient e-mail address(es), comma separated
reply The reply-to e-mail address
cc The carbon copy e-mail address(es), comma separated
bcc The blind carbon copy e-mail address(es), comma separated
subject The message subject
message The plain text message body
message_html The HTML message body
html If this evaluates to true, turns on HTML mode
attachments An array of file paths to attach. The array keys may be used for the paths, and the values for the name.
If the keys are numeric, the values are regarded as paths.
inline An array of inline (image) file paths to attach. If this is used, HTML mode (html) is switched on automatically.
search The array of patterns to be replaced by...
replace The array of replacements for the patterns
substitution A more complex structure for replacing placeholders and/or complete blocks, conditionally or repeatedly.

If key has been set, it tries to load the e-mail template identified by key (see e-mail templates), otherwise a blank email is initialized. The generated mail will be sent to the recipients defined by to, cc and bcc. If case of successful e-mail dispatching (to the configured SMTP server), the method send() returns true, otherwise false.

Sender domain validation

MailTemplate does ensure that only authorized mails are sent. Depending on the use case it ensures that the sending domain has a valid SPF-record and/or DKIM- and DMARC-Records.
Actual validation is implemented by NetManager.
This behavior can be adjusted to a specific use case using the following helpers:

Example: Require SPF, DKIM and DMARC authentication

$mail = new \Cx\Core\MailTemplate\Model\Entity\Mail();
$mail->requiresFullSenderAuthentication();
$mail->setFrom($senderEmail, $senderName);
$mail->addAddress($toEmailAddress);
$mail->Subject = $subject;
$mail->Body = $htmlBody;
$mail->AltBody = $plaintextBody;
// send process will fail if domain in $senderEmail has invalid SPF or
// DMARC record or DKIM signing fails
if (!$mail->send()) {
    \Message::error($mail->ErrorInfo);
}

Example: Ignore sender domain validation

1
2
3
4
5
6
7
8
9
$mail = new \Cx\Core\MailTemplate\Model\Entity\Mail();
$mail->ignoreSenderValidation();
$mail->setFrom($senderEmail, $senderName);
$mail->addAddress($toEmailAddress);
$mail->Subject = $subject;
$mail->Body = $htmlBody;
$mail->AltBody = $plaintextBody;
// mail will be sent even if SPF, DKIM and DMARC are invalid
$mail->send();

Live input validation

Add the CSS class senderAddress to a HTML-input-element to add a live sender domain validation to it. If strict1 validation is required, do add the attribute data-sender-validation="strict". Further if the validation shall be made against a specific SMTP-server, do add the attribute data-smtp-server-id="<id>".

Regular sender address validation

<input type="text" class="senderAddress" />

Strict sender address validation

<input type="text" class="senderAddress" data-sender-validation="strict" />

Regular sender address validation against specific SMTP-server

<input type="text" class="senderAddress" data-smtp-server-id="<id>" />

Where <id> must be replaced by the ID of the SMTP-server to validate against.

Manually check validation

To check if there are any sender domains in use that are not properly authenticated, the helper \Cx\Core\MailTemlate\Controller\ComponentController::hasIncompliantSenderDomains() can be used.

Example

1
2
3
if ($this->getComponent('MailTemplate')->hasIncompliantSenderDomains()) {
    \Message::warning('Incompliant sender domains are in use!');
}

Note

Sender domains being in use are collected by an event of the NetManager.

DKIM signing

If DKIM has been properly set up for a sender domain, then MailTemplate automatically signs the email using DKIM.

Note

When \Cx\Core\MailTemplate\Model\Entity\Mail::requiresFullSenderAuthentication() is set or when sending over an external SMTP-server, but DKIM singing fails (due to a misconfiguration), then the send process will be aborted.

E-Mail templates

E-mail templates provide the ability for custom tailored e-mail notifications that can be managed by a user over a GUI.

Management

Note

The default SystemComponentBackendController automatically ads a section for e-mail template management in the backend in case there are any templates by the viewing component present. So manual integration is therefore rarely required.

The management of e-mail templates can easily be integrated into a backend section as follows:

1
2
3
4
$htmlCode = \Cx\Core\MailTemplate\Controller\MailTemplate::overview(
    $this->getComponent()->getName(),
    'config'
)->get();

To integrate the management GUI directly into the view of the Setting configuration dialogue, do see separate section.

Sending

Sending an e-mail template is as easy as sending a non-template e-mail, with the exception that a key must be specified that does identify the e-mail template to be sent:

1
2
3
4
5
$options = [
    'key'     => 'order_confirmation',
    'section' => 'Shop',
];
\Cx\Core\MailTemplate\Controller\MailTemplate::send($options);

Any previously defined option by the e-mail template will be overwritten if it gets passed to send() as $options.

Placeholder support

A MailTemplate e-mail (both a template and non-template e-mail) does support template blocks and placeholders in the following form:

1
2
3
4
5
Placeholders (case insensitive):
[place_holder], [PLACEHOLDER] or [PLACEHOLDER2]

Conditional or repeated blocks:
[[BLOCK] ... [PLACEHOLDER] ... [BLOCK]]

Note

The format for placeholders and blocks differs from the common format used by the rest of Cloudrexx.

When sending an e-mail, the option substitution can then be used to pass the data that shall be used to parse the placeholders and blocks within an email. It is important to note, that not only the body (message) of an email does support placeholders and blocks, but all $options. Meaning that substitution will be applied to all set $options of an e-mail template.

Placeholders and blocks that are empty or not defined by substitution will be removed from the e-mail before it will be sent. If the latter is not intended, then instead of substitution, you could use search together with replace which will do a static search & replace on all $options of an e-mail template.

Examples

The following examples will use the following template:

[[MY_BLOCK] ... [MY_PLACEHOLDER] ... [MY_BLOCK]]
$options['substitution'] Output Notes
[
    'my_block' => [
        0 => [
            'MY_PLACEHOLDER' => 'Hello World'
        ],
    ],
]
... Hello World ...
If my_block or my_placeholder is missing in substitution, then the whole block will not be parsed, but removed from the e-mail.
[
    'my_block' => [
        0 => [
            'MY_PLACEHOLDER' => 'One',
        ],
        1 => [
            'MY_PLACEHOLDER' => 'Two',
        ],
    ],
]
... One ...
... Two ...

Warning

The additional array level between block and placeholders (or other blocks) is necessary - even for blocks without repetition. Therefore the following is wrong and will not work:

1
2
3
4
5
$options['substitution'] = [
    'my_block' => [
        'MY_PLACEHOLDER' => 'Hello World'
    ],
];

SMTP Relay

MailTemplate will use the default SMTP server (as set in Administration > Basic Configuration > E-mail Server) for relying mail.

Note

When using a cx env environment the SMTP server can be set through the environment variable CLX_SMTP_MTA_HOST.


  1. strict validation means that SPF, DKIM and DMARC must be valid. With non-strict validation only one of SPF and DKIM must be valid. DMARC is not required in non-strict validation. non-strict validation will be removed in the future and strict will become the sole validation method.