Mail extension

DrupalX makes it very easy to create a full HTML mail from a Twig template. Not only the message body but also all the information in the mail header (i.e. from, to, cc, subject etc.) as well as any files you'd like to attach, can be influenced directly from Twig via DrupalX's newly introduced "mail" statement.

In addition, you can automatically send a mail as soon as a form (provided by the "contact_form" module) is submitted. You only need to create your Twig mail template with a certain corresponding filename.

Prerequisites

DrupalX heavily relies on the great "mailsystem" and "swiftmailer" modules to make HTML mails possible. Make sure you have them installed if you want to send HTML mails. This is not required if you want to send text mails only. If you are using drush you can install them easily with:

drush pm-enable mailsystem swiftmailer

Once installed, make sure you select "Swift Mailer" as "Formatter" as well as "Sender" under "/admin/config/system/mailsystem". These should be the first two dropdown boxes.

The theme to use for rendering the mail as well as any other settings don't matter for DrupalX, you can keep the defaults.

In order to actually send HTML mails, the swiftmailer module in turn relies on the SwiftMailer class (hence its name, of course). You need to install that class via composer:

composer require swiftmailer/swiftmailer

Template files

Mail template files reside in the "templates/" folder of your theme just like any other templates. Since the exact folder doesn't matter, we recommend creating a sub-folder "mail" inside your templates-folder to make things a bit less confusing.

You can then create a file for your mail template. The file names always have the form "mail--[MAILID].html.twig" for HTML mails or "mail--[MAILID].txt.twig" for plain text mails. The "[MAILID]" can be any arbitary machine name under which you'd like to call your mail template later. If you, however, want to have DrupalX send that mail automatically on a form submit, you must use your form's ID as "[MAILID"].

If you have, for example a contact form with form ID/machine name "register", then you'd use the filename "mail--register.html.twig" for your template. Now, let's create a first template to see what it looks like:

{%
set Mail->from="example@drupal.org";
set Mail->to="info@drupalx.org";
set Mail->subject="Registration successful";
%}
<h1>Welcome</h1>
<p>Thank you for registering at DrupalX.</p>

As you can see, the current Mail object can be accessed within that template by using DrupalX's singleton operator.

Multiple mails per form submit

DrupalX can even send multiple mails per form submit. They can be totally different. Different recipients, different content. One mail can be HTML and another plain text etc. This feature is often useful if you want, for example, send the website owner a mail from a contact form and - at the same time - inform the visitor who filled out the form that his contact request has been submitted successfully by sending a confirmatory mail. There are many other examples where this might be useful.

So, how does it work? Well, fairly easy: The example in the previous paragraph uses the filename "mail--register.html.twig" for a form with ID "register". This mail is then sent automatically if a user submits that form. Now, if you create a second file called "mail--register--2.txt.twig", that mail will also be triggered. You can add even more templates "mail--register--3.html.twig", "mail--register--4.txt.twig" and so on. As you can see, those mails can arbitrarily be of type HTML or plain text.

Using form values

As you can easily see from the previous example, if you're sending the mail in response to a form submission, it is most often very desirable to include some of the submitted form data in your mail. You can simply use the DrupalX field accessor operator (#) for this. So let's extend our previous example - assuming we have a field "email" and a field "subject" in our form:

{%
set Mail->from=#email;
set Mail->to="info@drupalx.org";
set Mail->subject=#subject;
%}
<h1>Welcome</h1>
<p>Thank you for registering at DrupalX.</p>

Selecting recipients (to, cc, bcc)

As you've probably already noticed from the examples above, the recipient can be chosen with the "mail to is ..." statement. The recipient can be either a string containing a single email adress or an array of multiple email adresses:

{% set Mail->to=["info@drupalx.org","contact@drupalx.org","support@drupalx.org"] %}

Adding CC and BCC addresses works almost the same:

{%
set Mail->cc="copy@example.org";
set Mail->bcc=["blind1@test.com","blind2@test.com"];
%}

Attachments

If your form contains file fields, you can use the new "attach" statement to add those uploaded files to your mail:

{%
if #upload;
	do Mail->attach(#upload,"example.pdf");
endif
%}

This examples checks whether a field called "upload" contains a file, and if it does, it will be attached to the mail under the filename "example.pdf".

Redirects

After your form has been submitted and the mail has been sent, you probably want to redirect the user to a confirmation/success page. You can use the new "redirect" statement to redirect the user to a specific node. You can find that node e.g. by using a simple query:

{%
redirect to Node::query({title:"Mail sent successfully"})
%}

All of DrupalX's API can be used to determine that node. In the example above, the node is determined by its title. Of course, using some other query (e.g. loading a fixed node id or searching for a specific field content) would probably make more sense here, since a title can obviously change - it's up to you how you want to determine such a node.