Mail System in Drupal 7 and 8

Beginner’s guide to Mail System in Drupal 7 and 8

This blog is all about How Drupal handles the Mail system & the stages it has to go through.
In Drupal to sends an email we need to take care of two rules

  1. Declare all the required properties under hook_mail().
  2. Call drupal_mail() with argument for actually sending the email

However in the scenario like bigger & complex site the above steps won’t be enough. But Drupal gives us a Flexibility to customize email sending process, before that it’s necessary to know how stuff works behind the scenes first. In this article I’ll show you how you can customize and extend the Drupal mail system to fulfill your needs.

While sending an email drupal_mail() function uses system class for sending an email. Every mail system needs to implement MailSystemInterface class to declare own sending behaviour.
MailsystemInterface class uses two methods 1) format() and 2) mail() 

As you can get it from name itself the first method format() method is used for formatting an email before it get send. Second method mail() method defines the exact email sending behaviour.

Flow of drupal_mail()

  • Set up default email messages properties. 
  • Build email(subject, body, with other required parameters) by calling hook_mail().
  • Allows module to alter email by calling hook_mail_alter().
  • Check for the responsible mail interface system which will handle the email.
  • Format the email message using format() method of the called mail system class.
  • send email using mail() method of the called mail system class.
  • return the processed email.

So you can  understand better that mailsystem plays an important role while sending email. By default drupal uses DefaultMailSystem class to send email. Will discuss this class in more detail first, let’s check out drupal 7 mail system module.

Mail system module in drupal provides an Administrative UI and Developer API for managing the used email/plugin. Allow to use different backends for formatting and sending e-mails by default, per module and per mail key. Additionally, a theme can be configured that is used for sent mails. In Drupal 7, that must be enabled for each template, in Drupal 8, it works reliably for any template being rendered while building and sending e-mails.

Mail system configuration


Drupal 7 don’t provide administrative UI to adjust the mail_system variable which defines  “email key” => “mail system class” type key-value pairs which correspond to what mail system class will be used by drupal_mail() at a specific email key. This is the point where the Mail System module comes in. It allows you to adjust the mail_system variable by an administrative UI and it provides some other useful configuration options, too.

The Mail System module related settings can be found under the Configuration > System > Mail System path 
inside your Drupal installation.

Mail System Settings

The default-system “email key” always exists and it determines which mail system class will be used by default for all outgoing emails. As you can see its default value is DefaultMailSystem so this is the reason why this mail system class will be used by drupal_mail() by default. 

The mailsystem_theme key is a little bit different since it defines which theme will be used to render the emails. let's assume that there is a drupal mail system related module which uses a template file to render emails. The mentioned template file obviously belongs to a hook_theme() entry to be able to use it at appropriate theme() calls. 
The Mail System module checks every theme registry entry for a specific “mail theme” key/property and if it exists in a particular entry then the specified mailsystem_theme value will be used to search for more specific template files when the theme registry entry related theme hook will be called.

Site wide mailsystem configuration

New Class

Imagine you have two or more different mail system classes available in your system provided by different modules. Each one has a format() and a mail() method. Now you need a custom mail system class which would use the format() method from one mail system class and it would use the mail() method from another class. This is the point where the Mail System module’s  “New Class” tool comes in, since it allows you to easily combine the behavior of two mail system classes by selecting their format() and mail() method for the new class.

New class configuration

New Setting

As we have seen, the mail_system variable’s default-system email key defines the site-wide mail system class which will be used for all emails. However there could be a situation when mail system class is not enough. In a situation like these the Mail System module allows you to easily add new email keys to the mail_system variable by selecting a module and a specific email key from its hook_mail() implementation.

New mail system setting

Mostly use mail system classes
My suggestion to all the learners is, before you start writing your own mail system class it is a good idea to study the most commonly used ones, because there are already some of them that will complete your needs and save lot of time. 

Drupal's built-in default mail system class. If you don’t modify the site-wide mail system class then this one will be used by drupal_mail() by default.

DefaultMailSystem’s format() method enforces the emails' output as plain text, therefore it doesn't matter how your messages are formatted — the result will always be plain text. The mail() method of the class sends the emails via PHP's mail() function, so a correctly set up and working email sending service is required for it.

Email sending is an important task that affects most of your projects, therefore it is always good to know how to get the most out of the system. I hope this overview of the options help you to customizing and extending Drupal’s mail system helps you choose the best solution for your needs.