modMail

What is modMail?¶

modMail is an abstract class you extend to provide mail services in MODX. It cannot run by itself; an implementation class (such as PHPMailer) must extend it.

What is modPHPMailer?¶

modPHPMailer is a class that extends modMail to provide an implementation for the open source PHPMailer class.

Usage¶

The example below sends a Chunk as an HTML email through the bundled modPHPMailer:

$message = $modx->getChunk('myEmailTemplate');

$modx->getService('mail', 'mail.modPHPMailer');
$modx->mail->set(modMail::MAIL_BODY,$message);
$modx->mail->set(modMail::MAIL_FROM,'[email protected]');
$modx->mail->set(modMail::MAIL_FROM_NAME,'Johnny Tester');
$modx->mail->set(modMail::MAIL_SUBJECT,'Check out my new email template!');
$modx->mail->address('to','[email protected]');
$modx->mail->address('reply-to','[email protected]');
$modx->mail->setHTML(true);
if (!$modx->mail->send()) {
    $modx->log(modX::LOG_LEVEL_ERROR,'An error occurred while trying to send the email: '.$modx->mail->mailer->ErrorInfo);
}
$modx->mail->reset();

Call reset() before sending another message — it blanks all the fields. Every field is optional, so reply-to can be skipped when you don’t need it.

To reach several recipients, repeat address('to'):

$modx->mail->address('to','[email protected]');
$modx->mail->address('to','[email protected]');

The example above writes to the error log when the mail is not sent, which usually means a server misconfiguration.

Placeholders in your Chunk¶

The body can come from anywhere. The example above uses modX.getChunk (see its optional second argument there); you can also pass a static string to modMail::MAIL_BODY. Which placeholders appear in the body is up to you.

What if I want to use another email class?¶

Extend modMail with that class and load it with getService. You get all modMail functionality and provide the wrapper class yourself, as modPHPMailer does.

API and settings¶

Methods¶

Beyond the set(), address(), send() and reset() methods used above, the modPHPMailer implementation provides:

• header($header) — add a raw header to the message;
• attach($file, $name = '', $encoding = 'base64', $type = 'application/octet-stream') — attach a file;
• embedImage($image, $cid, $name = '', $encoding = 'base64', $type = 'application/octet-stream') — embed an inline image (referenced by $cid in the HTML body);
• clearEmbeddedImages() / clearAttachments() — remove previously added images/attachments before reusing the object;
• setHTML($toggle) — switch between plain-text and HTML mode (used in the example above);
• hasError() / getError() — check for and read the underlying mailer error;
• getDefaultAttributes() — the resolved attribute defaults (see below).

Attribute constants¶

set() and get() accept the keys defined as class constants on modMail:

• general: MAIL_BODY, MAIL_BODY_TEXT, MAIL_CHARSET, MAIL_CONTENT_TYPE, MAIL_ENCODING, MAIL_ENGINE, MAIL_ENGINE_PATH, MAIL_ERROR_INFO, MAIL_FROM, MAIL_FROM_NAME, MAIL_HOSTNAME, MAIL_LANGUAGE, MAIL_PRIORITY, MAIL_READ_TO, MAIL_SENDER, MAIL_SERVICE, MAIL_SUBJECT;
• SMTP: MAIL_SMTP_AUTH, MAIL_SMTP_HELO, MAIL_SMTP_HOSTS, MAIL_SMTP_KEEPALIVE, MAIL_SMTP_PASS, MAIL_SMTP_PORT, MAIL_SMTP_SECURE, MAIL_SMTP_AUTOTLS, MAIL_SMTP_SINGLE_TO, MAIL_SMTP_TIMEOUT, MAIL_SMTP_USER;
• DKIM: MAIL_DKIM_SELECTOR, MAIL_DKIM_IDENTITY, MAIL_DKIM_DOMAIN, MAIL_DKIM_PRIVATEKEYFILE, MAIL_DKIM_PRIVATEKEYSTRING, MAIL_DKIM_PASSPHRASE.

System settings¶

getDefaultAttributes() reads its defaults from system settings, so a site-wide mailer is configured without code. With mail_use_smtp enabled, the SMTP settings below are used instead of PHP mail().

See Sending mail for the manager-side configuration of these settings.

See Also¶

• MODX Services
• modX.getService
• Sending mail