Chris@0: mail() sends the email, which can Chris@0: * be reused if the exact same composed email is to be sent to multiple Chris@0: * recipients. Chris@0: * Chris@0: * Finding out what language to send the email with needs some consideration. Chris@0: * If you send email to a user, her preferred language should be fine, so use Chris@0: * \Drupal\Core\Session\AccountInterface::getPreferredAdminLangcode(). If you Chris@0: * send email based on form values filled on the page, there are two Chris@0: * additional choices if you are not sending the email to a user on the site. Chris@0: * You can either use the language used to generate the page or the site Chris@0: * default language. See Chris@0: * Drupal\Core\Language\LanguageManagerInterface::getDefaultLanguage(). The Chris@0: * former is good if sending email to the person filling the form, the later Chris@0: * is good if you send email to an address previously set up (like contact Chris@0: * addresses in a contact form). Chris@0: * Chris@0: * Taking care of always using the proper language is even more important when Chris@0: * sending emails in a row to multiple users. Hook_mail() abstracts whether Chris@0: * the mail text comes from an administrator setting or is static in the Chris@0: * source code. It should also deal with common mail tokens, only receiving Chris@0: * $params which are unique to the actual email at hand. Chris@0: * Chris@0: * An example: Chris@0: * Chris@0: * @code Chris@0: * function example_notify($accounts) { Chris@0: * foreach ($accounts as $account) { Chris@0: * $params['account'] = $account; Chris@0: * // example_mail() will be called based on the first Chris@0: * // MailManagerInterface->mail() parameter. Chris@0: * \Drupal::service('plugin.manager.mail')->mail('example', 'notice', $account->mail, $langcode, $params); Chris@0: * } Chris@0: * } Chris@0: * Chris@0: * function example_mail($key, &$message, $params) { Chris@0: * $data['user'] = $params['account']; Chris@0: * $options['langcode'] = $message['langcode']; Chris@0: * user_mail_tokens($variables, $data, $options); Chris@0: * switch($key) { Chris@0: * case 'notice': Chris@0: * // If the recipient can receive such notices by instant-message, do Chris@0: * // not send by email. Chris@0: * if (example_im_send($key, $message, $params)) { Chris@0: * $message['send'] = FALSE; Chris@0: * break; Chris@0: * } Chris@0: * $message['subject'] = t('Notification from @site', $variables, $options); Chris@0: * $message['body'][] = t("Dear @username\n\nThere is new content available on the site.", $variables, $options); Chris@0: * break; Chris@0: * } Chris@0: * } Chris@0: * @endcode Chris@0: * Chris@0: * Another example, which uses MailManagerInterface->mail() to format a Chris@0: * message for sending later: Chris@0: * Chris@0: * @code Chris@0: * $params = array('current_conditions' => $data); Chris@0: * $to = 'user@example.com'; Chris@0: * $message = \Drupal::service('plugin.manager.mail')->mail('example', 'notice', $to, $langcode, $params, FALSE); Chris@0: * // Only add to the spool if sending was not canceled. Chris@0: * if ($message['send']) { Chris@0: * example_spool_message($message); Chris@0: * } Chris@0: * @endcode Chris@0: * Chris@0: * @param string $module Chris@0: * A module name to invoke hook_mail() on. The {$module}_mail() hook will be Chris@0: * called to complete the $message structure which will already contain Chris@0: * common defaults. Chris@0: * @param string $key Chris@0: * A key to identify the email sent. The final message ID for email altering Chris@0: * will be {$module}_{$key}. Chris@0: * @param string $to Chris@0: * The email address or addresses where the message will be sent to. The Chris@0: * formatting of this string will be validated with the Chris@0: * @link http://php.net/manual/filter.filters.validate.php PHP email validation filter. @endlink Chris@0: * Some examples are: Chris@0: * - user@example.com Chris@0: * - user@example.com, anotheruser@example.com Chris@0: * - User Chris@0: * - User , Another User Chris@0: * @param string $langcode Chris@0: * Language code to use to compose the email. Chris@0: * @param array $params Chris@0: * (optional) Parameters to build the email. Chris@0: * @param string|null $reply Chris@0: * Optional email address to be used to answer. Chris@0: * @param bool $send Chris@0: * If TRUE, call an implementation of Chris@0: * \Drupal\Core\Mail\MailInterface->mail() to deliver the message, and Chris@0: * store the result in $message['result']. Modules implementing Chris@0: * hook_mail_alter() may cancel sending by setting $message['send'] to Chris@0: * FALSE. Chris@0: * Chris@0: * @return array Chris@0: * The $message array structure containing all details of the message. If Chris@0: * already sent ($send = TRUE), then the 'result' element will contain the Chris@0: * success indicator of the email, failure being already written to the Chris@0: * watchdog. (Success means nothing more than the message being accepted at Chris@0: * php-level, which still doesn't guarantee it to be delivered.) Chris@0: */ Chris@0: public function mail($module, $key, $to, $langcode, $params = [], $reply = NULL, $send = TRUE); Chris@0: Chris@0: }