Documentation | 2025.1

# Email configuration

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

If you make a configuration change, Swarm will not use it until the configuration cache has been reloaded, this forces Swarm to use the new configuration. You must be an admin or super user to reload the Swarm config cache. Navigate to the User id dropdown menu, select System Information, click the Cache Info tab, and click the Reload Configuration button.

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

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.

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.

When setting the path parameter, ensure that you do not use any other transport configuration options. See the Laminas Framework's File Transport Options and SMTP Transport Options for more information about the supported options.

Swarm supports the Laminas component versions in the LICENSE.txt file, features and functions in the Laminas documentation that were introduced in later versions of Laminas will not work with Swarm. The LICENSE.txt file is in the readme folder of your Swarm installation.

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.

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

Your search for returned results