email_example.module

Tracking 6.x-1.x branch
  1. drupal
    1. 6 contributions/examples/email_example/email_example.module
    2. 7 contributions/examples/email_example/email_example.module
    3. 8 contributions/examples/email_example/email_example.module

Example of how to use Drupal's mail API.

This example module provides two different examples of the Drupal email API.

  • defines a simple contact form and shows how to use drupal_mail() to send an e-mail (defined in hook_mail()) when the form is submitted.
  • shows how modules can alter emails defined by other Drupal modules or Core using hook_mail_alter by attaching a custom signature before they are sent.

Functions & methods

NameDescription
email_example_formThe contact form.
email_example_form_submitForm submission logic for the contact form.
email_example_form_validateForm validation logic for the contact form.
email_example_mailImplementation of hook_mail().
email_example_mail_alterImplementation of hook_mail_alter().
email_example_mail_sendSend an e-mail.
email_example_menuImplementation of hook_menu().

File

View source
  1. <?php
  2. /**
  3. * @file
  4. * Example of how to use Drupal's mail API.
  5. *
  6. * This example module provides two different examples of the Drupal email API.
  7. * - defines a simple contact form and shows how to use drupal_mail()
  8. * to send an e-mail (defined in hook_mail()) when the form is submitted.
  9. * - shows how modules can alter emails defined by other Drupal modules or
  10. * Core using hook_mail_alter by attaching a custom signature before
  11. * they are sent.
  12. */
  13. /**
  14. * @defgroup email_example Example: Email
  15. * @ingroup examples
  16. * @{
  17. * Example of mail API. (drupal 6)
  18. *
  19. * This example module provides two different examples of the Drupal email API.
  20. * - defines a simple contact form and shows how to use drupal_mail()
  21. * to send an e-mail (defined in hook_mail()) when the form is submitted.
  22. * - shows how modules can alter emails defined by other Drupal modules or
  23. * Core using hook_mail_alter by attaching a custom signature before
  24. * they are sent.
  25. *
  26. * This example is part of the Examples for Developers Project which you can download
  27. * and experiment with here: http://drupal.org/project/examples
  28. */
  29. /**
  30. * Implementation of hook_mail().
  31. *
  32. * This hook defines a list of possible e-mail templates that this module can
  33. * send. Each e-mail is given a unique identifier, or 'key'.
  34. *
  35. * $message comes in with some standard properties already set: 'to' address,
  36. * 'from' address, and a set of default 'headers' from drupal_mail(). The goal
  37. * of hook_mail() is to set the message's 'subject' and 'body' properties, as
  38. * well as make any adjustments to the headers that are necessary.
  39. *
  40. * The $params argument is an array which can hold any additional data required
  41. * to build the mail subject and body; for example, user-entered form data, or
  42. * some context information as to where the mail request came from.
  43. *
  44. * Note that hook_mail() is not actually a hook. It is only called for a single
  45. * module, the module named in the first argument of drupal_mail(). So it's
  46. * a callback of a type, but not a hook.
  47. */
  48. function email_example_mail($key, &$message, $params) {
  49. global $user;
  50. // Each message is associated with a language, which may or may not be the
  51. // current user's selected language, depending on the type of e-mail being
  52. // sent. This $language variable is used later in the t() calls for subject
  53. // and body to ensure the proper translation takes effect.
  54. $language = $message['language'];
  55. switch ($key) {
  56. // Send a simple message from the contact form.
  57. case 'contact_message':
  58. $message['subject'] = t('E-mail sent from @site-name', array('@site-name' => variable_get('site_name', 'Drupal')), $language->language);
  59. // Note that the message body is an array, not a string.
  60. $message['body'][] = t('@name sent you the following message:', array('@name' => $user->name), $language->language);
  61. // Because this is just user-entered text, we do not need to translate it.
  62. $message['body'][] = $params['message'];
  63. break;
  64. }
  65. }
  66. /**
  67. * Send an e-mail.
  68. *
  69. * @param $form_values
  70. * An array of values from the contact form fields that were submitted.
  71. * There are just two relevant items: $form_values['email'] and
  72. * $form_values['message'].
  73. */
  74. function email_example_mail_send($form_values) {
  75. // All system mails need to specify the module and template key (mirrored from
  76. // hook_mail()) that the message they want to send comes from.
  77. $module = 'email_example';
  78. $key = 'contact_message';
  79. // Specify 'to' and 'from' addresses.
  80. $to = $form_values['email'];
  81. $from = variable_get('site_mail', 'admin@example.com');
  82. // "params" loads in additional context for email content completion in
  83. // hook_mail(). In this case, we want to pass in the values the user entered
  84. // into the form, which include the message body in $form_values['message'].
  85. $params = $form_values;
  86. // The language of the e-mail. This will one of three values:
  87. // * user_preferred_language(): Used for sending mail to a particular website
  88. // user, so that the mail appears in their preferred language.
  89. // * global $language: Used when sending a mail back to the user currently
  90. // viewing the site. This will send it in the language they're currently
  91. // using.
  92. // * language_default(): Used when sending mail to a pre-existing, 'neutral'
  93. // address, such as the system e-mail address, or when you're unsure of the
  94. // language preferences of the intended recipient.
  95. //
  96. // Since in our case, we are sending a message to a random e-mail address that
  97. // is not necessarily tied to a user account, we will use the site's default
  98. // language.
  99. $language = language_default();
  100. // Whether or not to automatically send the mail when drupal_mail() is
  101. // called. This defaults to TRUE, and is normally what you want unless you
  102. // need to do additional processing before drupal_mail_send() is called.
  103. $send = TRUE;
  104. // Send the mail, and check for success. Note that this does not guarantee
  105. // message delivery; only that there were no PHP-related issues encountered
  106. // while sending.
  107. $result = drupal_mail($module, $key, $to, $language, $params, $from, $send);
  108. if ($result['result'] == TRUE) {
  109. drupal_set_message(t('Your message has been sent.'));
  110. }
  111. else {
  112. drupal_set_message(t('There was a problem sending your message and it was not sent.'), 'error');
  113. }
  114. }
  115. /**
  116. * Implementation of hook_mail_alter().
  117. *
  118. * This function is not required to send an email using Drupal's mail system.
  119. *
  120. * Hook_mail_alter() provides an interface to alter any aspect of email sent by
  121. * Drupal. You can use this hook to add a common site footer to all outgoing
  122. * email, add extra header fields, and/or modify the email in anyway. HTML-izing
  123. * the outgoing email is one possibility.
  124. */
  125. function email_example_mail_alter(&$message) {
  126. // For the purpose of this example, modify all the outgoing messages and
  127. // attach a site signature. The signature will be translated to the language
  128. // in which message was built.
  129. $signature = t("\n--\nMail altered by email_example module.", array(), $message['language']->language);
  130. if (is_array($message['body'])) {
  131. $message['body'][] = $signature;
  132. }
  133. else { // Some modules use the body as a string, erroneously.
  134. $message['body'] .= $signature;
  135. }
  136. }
  137. ///// Supporting functions ////
  138. /**
  139. * Implementation of hook_menu().
  140. *
  141. * Set up a page with an e-mail contact form on it.
  142. */
  143. function email_example_menu() {
  144. $items['example/email_example'] = array(
  145. 'title' => 'E-mail Example: contact form',
  146. 'page callback' => 'drupal_get_form',
  147. 'page arguments' => array('email_example_form'),
  148. 'access arguments' => array('access content'),
  149. );
  150. return $items;
  151. }
  152. /**
  153. * The contact form.
  154. */
  155. function email_example_form() {
  156. $form['intro'] = array(
  157. '#value' => t('Use this form to send a message to an e-mail address. No spamming!'),
  158. );
  159. $form['email'] = array(
  160. '#type' => 'textfield',
  161. '#title' => t('E-mail address'),
  162. '#required' => TRUE,
  163. );
  164. $form['message'] = array(
  165. '#type' => 'textarea',
  166. '#title' => t('Message'),
  167. '#required' => TRUE,
  168. );
  169. $form['submit'] = array(
  170. '#type' => 'submit',
  171. '#value' => t('Submit'),
  172. );
  173. return $form;
  174. }
  175. /**
  176. * Form validation logic for the contact form.
  177. */
  178. function email_example_form_validate($form, &$form_state) {
  179. if (!valid_email_address($form_state['values']['email'])) {
  180. form_set_error('email', t('That e-mail address is not valid.'));
  181. }
  182. }
  183. /**
  184. * Form submission logic for the contact form.
  185. */
  186. function email_example_form_submit($form, &$form_state) {
  187. email_example_mail_send($form_state['values']);
  188. }
  189. /**
  190. * @} End of "defgroup email_example".
  191. */