Mailsystem

The mailsystem module provides an Administrative UI and Developers API for managing the mail backend/plugin. for Drupal 7 and 8.

For understanding how the Mailsystem module fits into Drupal's core mail system, this blog post provides a thorough explanation.

Administrative UI Drupal 7

The Mail System module supports using one mail system to format your messages, and another to mail them. For an example of how to use this module, this tutorial explains how you may combine the rich formatting options of the HTML Mail module with the flexible sending options of the SMTP Authentication Support module.

Modules and Keys as Identifiers

A MailSystemInterface class can be associated with a module and optionally with a key. The key is part of the call made to drupal_mail() in the module. For example, if we want to use a specific MailSystemInterface class with Webform module, we look in the module for:

$message = drupal_mail('webform', 'submission', $address, $language, $mail_params, $email['from']);

The first parameter is the module name "webform" and the 2nd is the key "submission". So when we add our new setting in MailSystem, we select the module name (Webform), and enter the key (submission) exactly as it is used within that module.

The key, however, is optional. If we leave it blank then the class will be used for all emails being created with Webform.

Developers API Drupal 8

The configuration is managed in the mailsystem.settings configuration object. It is recommended to not force a certain value but let users enable the desired mail plugin and just point them to the settings page.

Developers API Drupal 7

A module example with a MailSystemInterface implementation called ExampleMailSystem should add the following in its example.install file:

/**
 * Implements hook_enable().
 */
function example_enable() {
  mailsystem_set(array('example' => 'ExampleMailSystem'));
}
/**
 * Implements hook_disable().
 */
function example_disable() {
  mailsystem_clear(array('example' => 'ExampleMailSystem'));
}

The above settings allow mail sent by example to use ExampleMailSystem. To make ExampleMailSystem the site-wide default for sending mail:

mailsystem_set(array(mailsystem_default_id() => 'ExampleMailSystem'));

To restore the default mail system:

mailsystem_set(array(mailsystem_default_id() => mailsystem_default_value()));

Or simply:

mailsystem_set(mailsystem_defaults());

If module example relies on dependency foo and its FooMailSystem class, then the example.install code should like like this:

/**
 * Implements hook_enable().
 */
function example_enable() {
  mailsystem_set(array('example' => 'FooMailSystem'));
}
/**
 * Implements hook_disable().
 */
function example_disable() {
  mailsystem_clear(array('example' => ''));
}

If module example only wants to use FooMailSystem when sending emails with a key of examail, then the example.install code should look like this:

/**
 * Implements hook_enable().
 */
function example_enable() {
  mailsystem_set(array('example_examail' => 'FooMailSystem'));
}
/**
 * Implements hook_disable().
 */
function example_disable() {
  mailsystem_clear(array('example_examail' => ''));
}

(New in 2.x branch)

To change the site-wide defaults to use the FooMailSystem for formatting messages and the BarMailSystem for sending them:

mailsystem_set(
  array(
    mailsystem_default_id() => array(
      'format' => 'FooMailSystem',
      'mail' => 'BarMailSystem',
    ),
  )
);

To change the site-wide defaults to use the FooMailSystem for sending messages, while continuing to use the current system for formatting them:

mailsystem_set(
  array(
    mailsystem_default_id() => array(
      'mail' => 'FooMailsystem',
    ),
  )
);