MailInterface.php 2.59 KB
Newer Older
1 2 3 4 5 6
<?php

namespace Drupal\Core\Mail;

/**
 * Defines an interface for pluggable mail back-ends.
7 8 9 10
 *
 * @see \Drupal\Core\Annotation\Mail
 * @see \Drupal\Core\Mail\MailManager
 * @see plugin_api
11 12 13 14
 */
interface MailInterface {

  /**
15
   * Formats a message prior to sending.
16
   *
17 18
   * Allows to preprocess, format, and postprocess a mail message before it is
   * passed to the sending system. By default, all messages may contain HTML and
19 20 21 22
   * are converted to plain-text by the Drupal\Core\Mail\Plugin\Mail\PhpMail
   * implementation. For example, an alternative implementation could override
   * the default implementation and also sanitize the HTML for usage in a MIME-
   * encoded email, but still invoking the Drupal\Core\Mail\Plugin\Mail\PhpMail
23 24
   * implementation to generate an alternate plain-text version for sending.
   *
25 26 27 28 29
   * @param array $message
   *   A message array, as described in hook_mail_alter().
   *
   * @return array
   *   The formatted $message.
30 31
   *
   * @see \Drupal\Core\Mail\MailManagerInterface
32
   */
33
  public function format(array $message);
34 35

  /**
36
   * Sends a message composed by \Drupal\Core\Mail\MailManagerInterface->mail().
37 38 39
   *
   * @param array $message
   *   Message array with at least the following elements:
40
   *   - id: A unique identifier of the email type. Examples: 'contact_user_copy',
41 42
   *     'user_password_reset'.
   *   - to: The mail address or addresses where the message will be sent to.
43
   *     The formatting of this string will be validated with the
44
   *     @link http://php.net/manual/filter.filters.validate.php PHP email validation filter. @endlink
45
   *     Some examples:
46 47 48 49
   *     - user@example.com
   *     - user@example.com, anotheruser@example.com
   *     - User <user@example.com>
   *     - User <user@example.com>, Another User <anotheruser@example.com>
50
   *   - subject: Subject of the email to be sent. This must not contain any
51 52
   *     newline characters, or the mail may not be sent properly. The subject
   *     is converted to plain text by the mail plugin manager.
53
   *   - body: Message to be sent. Accepts both CRLF and LF line-endings.
54 55
   *     Email bodies must be wrapped. For smart plain text wrapping you can use
   *     \Drupal\Core\Mail\MailFormatHelper::wrapMail() .
56 57 58
   *   - headers: Associative array containing all additional mail headers not
   *     defined by one of the other parameters.  PHP's mail() looks for Cc and
   *     Bcc headers and sends the mail to addresses in these headers too.
59 60 61 62
   *
   * @return bool
   *   TRUE if the mail was successfully accepted for delivery, otherwise FALSE.
   */
63
  public function mail(array $message);
64

65
}