1. interface
  2. Drupal
  3. \
  4. Core
  5. \
  6. Mail
  7. \
  8. MailManagerInterface

MailManagerInterface

interface MailManagerInterface implements PluginManagerInterface (View source)

Provides an interface for sending mail.

Methods

mixed
getDefinition(string $plugin_id, bool $exception_on_invalid = TRUE)

Gets a specific plugin definition.

from  DiscoveryInterface
array
getDefinitions()

Gets the definition of all plugins for this type.

from  DiscoveryInterface
bool
hasDefinition(string $plugin_id)

Indicates if a specific plugin definition exists.

from  DiscoveryInterface
object
createInstance(string $plugin_id, array $configuration = [])

Creates a pre-configured instance of a plugin.

from  FactoryInterface
object|false
getInstance(array $options)

Gets a preconfigured instance of a plugin.

from  MapperInterface
array
mail(string $module, string $key, string $to, string $langcode, array $params = [], string|null $reply = NULL, bool $send = TRUE)

Composes and optionally sends an email message.

Details

in DiscoveryInterface at line 28
mixed getDefinition(string $plugin_id, bool $exception_on_invalid = TRUE)

Gets a specific plugin definition.

Parameters

string $plugin_id

A plugin id.
bool $exception_on_invalid

(optional) If TRUE, an invalid plugin ID will throw an exception.

Return Value

mixed

A plugin definition, or NULL if the plugin ID is invalid and $exception_on_invalid is FALSE.

Exceptions

PluginNotFoundException

in DiscoveryInterface at line 39
array getDefinitions()

Gets the definition of all plugins for this type.

Return Value

array

An array of plugin definitions (empty array if no definitions were found). Keys are plugin IDs.

See also

FilteredPluginManagerInterface::getFilteredDefinitions

in DiscoveryInterface at line 50
bool hasDefinition(string $plugin_id)

Indicates if a specific plugin definition exists.

Parameters

string $plugin_id

A plugin ID.

Return Value

bool

TRUE if the definition exists, FALSE otherwise.

in FactoryInterface at line 24
object createInstance(string $plugin_id, array $configuration = [])

Creates a pre-configured instance of a plugin.

Parameters

string $plugin_id

The ID of the plugin being instantiated.
array $configuration

An array of configuration relevant to the plugin instance.

Return Value

object

A fully configured plugin instance.

Exceptions

PluginException

in MapperInterface at line 28
object|false getInstance(array $options)

Gets a preconfigured instance of a plugin.

Parameters

array $options

An array of options that can be used to determine a suitable plugin to instantiate and how to configure it.

Return Value

object|false

A fully configured plugin instance. The interface of the plugin instance will depend on the plugin type. If no instance can be retrieved, FALSE will be returned.

at line 124
array mail(string $module, string $key, string $to, string $langcode, array $params = [], string|null $reply = NULL, bool $send = TRUE)

Composes and optionally sends an email message.

Sending an email works with defining an email template (subject, text and possibly email headers) and the replacement values to use in the appropriate places in the template. Processed email templates are requested from hook_mail() from the module sending the email. Any module can modify the composed email message array using hook_mail_alter(). Finally \Drupal::service('plugin.manager.mail')->mail() sends the email, which can be reused if the exact same composed email is to be sent to multiple recipients.

Finding out what language to send the email with needs some consideration. If you send email to a user, use \Drupal\Core\Session\AccountInterface::getPreferredAdminLangcode(). If you send email based on form values filled on the page, there are two additional choices if you are not sending the email to a user on the site. You can either use the language used to generate the page or the site default language. See Drupal\Core\Language\LanguageManagerInterface::getDefaultLanguage(). The former is good if sending email to the person filling the form, the later is good if you send email to an address previously set up (like contact addresses in a contact form).

Taking care of always using the proper language is even more important when sending emails in a row to multiple users. Hook_mail() abstracts whether the mail text comes from an administrator setting or is static in the source code. It should also deal with common mail tokens, only receiving $params which are unique to the actual email at hand.

An example:

Parameters

string $module

A module name to invoke hook_mail() on. The {$module}_mail() hook will be called to complete the $message structure which will already contain common defaults.
string $key

A key to identify the email sent. The final message ID for email altering will be {$module}_{$key}.
string $to

The email address or addresses where the message will be sent to. The formatting of this string will be validated with the @link http://php.net/manual/filter.filters.validate.php PHP email validation filter. @endlink Some examples are:
string $langcode

Language code to use to compose the email.
array $params

(optional) Parameters to build the email. Use the key '_error_message' to provide translatable markup to display as a message if an error occurs, or set this to false to disable error display.
string|null $reply

Optional email address to be used to answer.
bool $send

If TRUE, call an implementation of \Drupal\Core\Mail\MailInterface->mail() to deliver the message, and store the result in $message['result']. Modules implementing hook_mail_alter() may cancel sending by setting $message['send'] to FALSE.

Return Value

array

The $message array structure containing all details of the message. If already sent ($send = TRUE), then the 'result' element will contain the success indicator of the email, failure being already written to the watchdog. (Success means nothing more than the message being accepted at php-level, which still doesn't guarantee it to be delivered.)