Mail Package Configuration

The mail Package Configuration defines defaults that can be overridden in config.php.

File: <webcomand>/packages/io_comand_email/config/mail.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' => 'support@webcomand.com',

    // 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' => 'test@email.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'
];

Filters

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.

Match

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' => 'support@webcomand.com'],

// Matches all recipients for either domain
'match' => ['to' => ['@client1.com', '@client2.com']]

Action

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

Options are specific to the different actions. Currently only the redirect action supports options. See the example below for details.

Example

With the filters below, emails are handled as follows:

TO: support@webcomand.com, SUBJECT: System Cleanup -- Completed With Errors
This is sent as-is (Rule 1)
TO: jim@client1.com, forms@webcomand.com, SUBJECT: Sales Order #12345
This is sent just to forms@webcomand.com (Rule 2)
TO: jim@client1.com, SUBJECT: Weekly Sales Report
This is not sent (Rule 2)
TO: jimsclient@email.com, SUBJECT: Your Sales Receipt #12345
This is sent to support@webcomand.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 support@webcomand.com
        ['match' => true, 'action' => 'redirect', 'options' => [
            'to' => 'support@webcomand.com'
        ]
    ]