Email configuration

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

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
            // for more information about available options when using the path parameter, see Transport section
            // '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,

        // change the email subject prefix, the default prefix is '[Swarm]'
        // 'subject_prefix' => '[Swarm]',
 
        // Control email thread indexing
        // 'index-conversations' => true, // ['true'|'false'] default is true, email thread indexing is turned on
    ),

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.

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.

When a group mailing list is enabled it overrides the group member's preference set for the notify_self configurable in the SWARM_ROOT/data/config.php file. So even when the notify_self configurable is set to false the group member will receive an email notification.

There is a caveat that if a user is a group member and the same user is added individually to the review and has set the notify_self configurable to true, the user receives two email notifications.

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,
),

Email subject prefix

The subject_prefix item withing the mail block sets the prefix for the subject line of emails sent by Swarm. By default this is set to [Swarm].

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

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, the mail transport will create a new file for each email message and write it to the path directory. This path must already exist and be writable by the web server user.

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/2019.1/1798019 (2019/05/09)

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/2019.1/1798019 (2019/05/09)

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/2019.1/1798019 (2019/05/09)

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/2019.1/1798019 (2019/05/09)

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.

Email thread indexing

By default, Swarm indexes emails so that email conversations are threaded correctly in your email clients. If you find that your email clients are not displaying Swarm email threads correctly, disable thread indexing. To disable indexing, use the following configuration block and set to false:

<?php
    // this block should be a peer of 'p4'
    'mail' => array(
        'index-conversations' => false, // ['true'|'false'] default is 'true' 
    ),