- ⌂ io_comand_email
- Content Types
Mail Package Configuration
The mail Package Configuration defines defaults that can be overridden in config.php.
<?php /** * Defines configuration for the COMAND API's email capabilities. */ $config = [ // Emails will only be sent from webCOMAND if this is TRUE 'enabled' => TRUE, // The default FROM address for ougoing emails, if not specified 'default_from' => 'firstname.lastname@example.org', // Comma-separated addresses to BCC on all outgoing emails 'bcc' => '', // Log information about sent emails and failures 'mail_log' => [ 'enabled' => TRUE, 'filename' => COMAND_HOME.'/files/logs/webcomand/mail_%Y%m%d.log', 'level' => 6 // 4=errors, 5=warnings, 6=notices, 7=info, 8=verbose ], // Rules used to filter and manipulate outgoing emails 'filters' => [ [ 'match' => true, 'action' => 'redirect', 'options' => ['to' => 'email@example.com'] ] ], // Optional array of email headers to include in all outgoing emails //'headers' => ['User Agent' => 'webCOMAND 3.0'], // Email adapter and lib path to send emails with, if not specified //'adapter_class' => '\\io_comand_email\\senders\\PHPMail', //'library_path' => COMAND_HOME . '/libs/PHPMailer/src' ];
The filters configuration option can be used to define rules that change the behavior of the mail code depending on the filter criteria. This can be used in one of several ways, including:
- blocking any emails from going to anyone except certain domains or individual recipients
- redirecting emails to certain recipients instead to others with a message
This functionality is especially useful in development or test environments, to allow emails to be sent, such as background process errors to system administrators, while blocking other emails sent from tasks under development.
This filter list works on recipients, and changes the recipients of an email in the to, cc and bcc lists according to the filter matches. Zero or more filters can be specified. The first matching filter for a particular recipient "wins" and the action will be performed without considering further filters.
Filters have three main components:
- match - the criteria to match recipients on
- action - the action to perform when there's a match, i.e. block or redirect
- options - extra options to use when performing the action, which are specific to that action
If, after applying all filters, there are no remaining recipients in the to recipient list, the email will not be sent, even if there are remaining recipients in the cc and bcc recipient lists.
You can match any email recipient by using 'true'.
'match' => true
You can match on individual recipients using one or more fully qualified email addresses or domains.
// TO is shorthand and will match on any TO, CC, or BCC recipients 'match' => ['to' => 'firstname.lastname@example.org'], // Matches all recipients for either domain 'match' => ['to' => ['@client1.com', '@client2.com']]
Actions are one of the following:
- block - the recipient is removed from the email
- redirect - remove the recipient and replace with another
- send - leave the recipient in the email
Options are specific to the different actions. Currently only the redirect action supports options. See the example below for details.
With the filters below, emails are handled as follows:
- TO: email@example.com, SUBJECT: System Cleanup -- Completed With Errors
This is sent as-is (Rule 1)
- TO: firstname.lastname@example.org, email@example.com, SUBJECT: Sales Order #12345
This is sent just to firstname.lastname@example.org (Rule 2)
- TO: email@example.com, SUBJECT: Weekly Sales Report
This is not sent (Rule 2)
- TO: firstname.lastname@example.org, SUBJECT: Your Sales Receipt #12345
This is sent to email@example.com (Rule 3)
'filters' => [ // email recipients with @webcomand.com will proceed normally ['match' => ['to' => '@webcomand.com'], 'action' => 'send'], // email recipients with @client1.com will be blocked ['match' => ['to' => '@client1.com'], 'action' => 'block'], // any other email recipient is stripped and replaced with firstname.lastname@example.org ['match' => true, 'action' => 'redirect', 'options' => [ 'to' => 'email@example.com' ] ]