Email configuration

Swarm's email delivery is controlled by the mail configuration block in the data/config.php file. Here is an example: 

<?php
    // this block should be a peer of 'p4'
    'mail' => array(
        // 'sender' => '[email protected]',   // defaults to 'notifications@hostname'
        'transport' => array(
            'name' => 'localhost',          // name of SMTP host
            'host' => '127.0.0.1',          // host/IP of SMTP host
            'port' => 587,                  // SMTP host listening port
            'connection_class'  => 'plain', // 'smtp', 'plain', 'login', 'crammd5'
            'connection_config' => array(   // include when auth required to send
                'username'  => 'user',      // user on SMTP host
                'password'  => 'pass',      // password for user on SMTP host
                'ssl'       => 'tls',       // empty, 'tls', or 'ssl'
            ),

            // override email deliveries and store all messages in this path
            // 'path' => '/var/spool/swarm',
        ),

        // override regular recipients; send email only to these addresses
        // 'recipients' => array(
        //     '[email protected]',
        //     '[email protected]',
        // ),

        // blind carbon-copy recipients
        // 'use_bcc' => true,

        // suppress reply-to header
        // 'use_replyto' => false,
    ),

Note

Without any mail configuration in the data/config.php file, Swarm attempts to send email according to PHP's configuration, found in the php.ini file. By default, the configuration in php.ini relies on SendMail being installed.

Important

Email delivery for events related to restricted changes is disabled by default. See “Restricted Changes” for details on how to enable restricted change notifications.

Sender

The sender item within the mail block specifies the sender email address that should be used for all notification email messages. The default value is: 

notifications@hostname

hostname is the name of the host running Swarm, or when specified with the “Environment” configuration.

Transport

The transport block within the mail block defines which mail server Swarm should use to send email notifications. Most of the items in this block can be omitted, or included as needed. See the Zend Framework's Mail Transport Configuration Options for a description of most fields and their default values.

Swarm uses the custom path item to direct all email messages to a directory instead of attempting delivery via SMTP. For details, see “Save all messages to disk”.

Recipients

The recipients item within the mail block allows you to specify a list of recipients that should receive email notifications, overriding the normal recipients. This is useful if you need to debug mail deliveries. 

<?php
    // this block should be a peer of 'p4'
    'mail' => array(
        'recipients' => array(
            '[email protected]',
            '[email protected]',
        ),
    ),

Any number of recipients can be defined. If the array is empty, email notifications are delivered to the original recipients.

Use BCC

The use_bcc item within the mail block allows you to address recipients using the BCC email field. Setting the value to true causes Swarm to use the Bcc: field in notifications instead of the To: field, concealing the email addresses of all recipients. 

<?php
    // this block should be a peer of 'p4'
    'mail' => array(
        'use_bcc' => true,
    ),

Use Reply-To

The use_replyto item within the mail block allows you to suppress populating the Reply-To email field. Setting the value to false causes Swarm to omit the Reply-To: field in notifications; by default, it is populated with the author's name and email address. When this field is true, users receiving an email notification can simply reply to the email and their response will be addressed to the author. 

<?php
    // this block should be a peer of 'p4'
    'mail' => array(
        'use_replyto' => false,
    ),

Save all messages to disk

For testing purposes, you may want to send all email to disk without attempting to send it to recipients. Use the following configuration block to accomplish this: 

<?php
    // this block should be a peer of 'p4'
    'mail' => array(
        'transport'  => array('path' => MAIL_PATH),
    ),

<MAIL_PATH> should be replaced with the absolute path where email messages should be written. This path must already exist and be writable by the web server user.

Note

Use of the path item causes Swarm to ignore all other configuration within the transport block. This is why path is commented out in the main example.