Notifications and mail from applications #

This page is for application creators whose application sends mail: confirmations, reminders, reports. Exponential passes every mail through a mail gate that applies recipients' preferences, and has a notification system for mail triggered by content events (Mail preferences for developers, Notifications for developers).

Contents #

1. Sending a mail
2. Categories and the gate
3. Transports and testing
4. Notifications on content events
5. Rules

Sending a mail #

$ini = eZINI::instance();
$mail = new eZMail();
$mail->setSender( $ini->variable( 'MailSettings', 'EmailSender' ) ?: $ini->variable( 'MailSettings', 'AdminEmail' ) );
$mail->addReceiver( $address );
$mail->setSubject( $subject );
$mail->setBody( $text );
$mail->setCategory( 'events' );
eZMailTransport::send( $mail );

Build the body from a template ($tpl->fetch( 'design:expdemo/mail/reminder.tpl' )) so sites can change the wording.

Categories and the gate #

• Every mail has a category (setCategory()); a category is essential (always sent: security, orders, legal) or optional (only to recipients who turned it on).
• eZMailTransport::send() hands every mail to expMailGate::dispatch(), which decides per recipient, adds the footer and unsubscribe headers, and logs the blocked ones.
• Mail without a category is sent unchanged and logged as uncategorized; give every mail a category.
• A category of your own is declared in settings (3. A category of your own).

Transports and testing #

site.ini [MailSettings] Transport is sendmail, smtp or file; the file transport writes each mail to a file, which is how to test without sending (10.4 Mail, 8. Testing without sending mail). An override in settings/override/ wins over a siteaccess setting: check which transport is really in effect with ./console exp:ini where site.ini/MailSettings/Transport <siteaccess> before a test.

Notifications on content events #

For "tell people when something is published", write a notification event type and a handler instead of sending mail in a workflow: the notification system collects events, lets users subscribe and sends in the frequent cron part (2. An event type and a handler).

Rules #

• Always set a sender; never a visitor's address as From.
• Test addresses end in reserved domains (example.com, .invalid); never mail real people from a test.
• Do not split recipient lists yourself; the gate does, with each recipient's own unsubscribe link.
• Slow or bulk mail goes through a queue or cron, not the web request.

Related pages #

• Mail preferences
• Notifications
• Queues with expqueue
• Free documentation: this page is free to copy, translate and improve under the GNU FDL 1.3.