Email configuration

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

<?php
    // this block should be a peer of 'p4'
    'mail' => array(
        // 'sender' => 'swarm@my.domain',   // 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(
        //     'user1@my.domain',
        //     'user2@my.domain',
        // ),

        // send notifications of comments to comment authors?
        'notify_self' => false,

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

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

Note

Without any mail configuration in the SWARM_ROOT/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(
            'user1@my.domain',
            'user2@my.domain',
        ),
    ),

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

notify_self

The notify_self item within the mail block specifies whether comment authors should receive an email for their comments. The default value is false. When set to true, comment authors receive an email notification for their own comments.

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.

Email headers

Swarm sends out notification emails that contain custom headers which email programs can use for automatic filtering. Emails also contain headers to ensure they are correctly threaded in email clients which support doing so.

All Swarm emails contain the following headers, which can be used to identify which Swarm server they came from: 

X-Swarm-Host: swarm.perforce.com
X-Swarm-Version: SWARM/2017.1/1500036 (2017/03/27)

The exact values may differ according to the version of Swarm you are running, and its configuration.

If a notification is applicable to one or more projects, then each project will be listed in the X-Swarm-Project header, which contains a list of one or more project names. Reviews may span multiple projects, so in this case a single email is sent out with each project listed. 

X-Swarm-Project: gemini, apollo
X-Swarm-Host: swarm.perforce.com
X-Swarm-Version: SWARM/2017.1/1500036 (2017/03/27)

If one or more of the applicable projects is private, then two or more emails may be sent. In order for the existance of the private project to be hidden from non-members, any email sent to them will not contain references to the private project. Members of each private project will receive an email tailored to them which contains references to that private project. The email to the non-private projects will not contain references to any of the private projects in the X-Swarm-Project header.

For example, if a review spans three projects, called Gemini, Apollo and Ultra, where Ultra is a private project, then members of projects Gemini and Apollo will receive an email with the following headers: 

X-Swarm-Project: gemini, apollo
X-Swarm-Host: swarm.perforce.com
X-Swarm-Version: SWARM/2017.1/1500036 (2017/03/27)

Members of the Ultra project will receive an email with the following header: 

X-Swarm-Project: ultra
X-Swarm-Host: swarm.perforce.com
X-Swarm-Version: SWARM/2017.1/1500036 (2017/03/27)

This can result in users receiving two notification emails (if they are members of Ultra and one of the other two projects), but privacy for the private project is preserved.