Sending emails

When we want to send emails from an online application, we need to deal with the following things:

What will be the form and content of the email
This is, of course, the most important thing - how the email will look like, what the content will be, and so on.

Jet is a MVC framework so it is logical that the MVC principle will be used for generating emails.

The email sending subsystem therefore contains a template system that uses MVC_View for generation.
How the mail will actually be sent
And of course there must be something that represents the email itself and also a backend that takes care of actually sending it. The backend must of course be replaceable with another implementation.
Sender of the mail
A large application usually sends a variety of different emails. Typically, for example, an e-shop that sends order confirmations, various informational emails to customers, but also various system notifications (for example, notifications about changes at the supplier, warnings about non-standard conditions, and so on).

Each such email will belong to a different subject area and each such area will have a different sender. For example, an order confirmation will be sent from the address info@ and a system warning from the email system@ and so on.

And to keep this in order, it is important to have some system to keep track of these senders.

Now let's go over all of this in detail.

Senders

When installing the sample application, you may have noticed that the installer required you to enter information defining the default sender of emails (at least an email address and optionally a name).

Senders are defined using the application configuration system. It is therefore a configuration that the end user is expected to be able to modify themselves, either in the installer or in the administration using a tool that you can develop for your users.

You have defined one sender in the installer because at least one sender must be defined, but in practice it is expected that in large applications there will be more senders. As mentioned and explained above. The installer and/or configuration tools of your real application should take this into account.

Let's see how it works. Each sender must have an ID. The ID is a unique text string. I highly recommend creating constants within your application for sender IDs. One constant representing the sender ID is already directly in Jet and that is Mailing::DEFAULT_SENDER_ID having the value default. The other IDs are up to you.

Senders are handled via the configuration definition, represented by the Jet\Mailing_Config class, which you can access by the following:


Mailing::getConfig()

So if you need the details of a particular sender (for example, their email address), you can do this:


$sender_email = Mailing::getConfig()->getSender( MyApp::SOME_SENDER_ID )->getEmail();

Of course, senders can be added, removed and so on. See classes Jet\Mailing_Config and Jet\Mailing_Config_Sender

Email templates

To have the whole application in MVC and only the form of emails to build "all sorts of fiddly" and not to stick to the MVC paradigm is really not only "not nice", but also very impractical (I tried it myself).

For this reason, there is an email template system in Jet. You can find some sample templates in the sample application, so let's use one of them to demonstrate.

By default, the templates are located in the ~/application/email-templates directory (which you can of course change using system configuration SysConf_Jet_Mailing)

In this directory you will also find subdirectories whose names correspond to the location codes. So, for example, the Czech versions of the templates are in the cs_CZ directory.

And in this directory there are already individual templates.

But let's still say that every template has an ID. Let's take as an example the email template that is sent when a new access to the administration is established. This template has an ID of administrator/user_welcome and the directory corresponds to that. Thus, the English version of the welcome email template for a new administrator can be found in the ~/application/email-templates/cs_CZ/administrator/user_welcome/ directory.

In this directory you will already find these three files, actually view scripts:

body_html.phtml
Generates the HTML version of the email
body_txt.phtml
Generates a text version of the email
subject.phtml
Generates the subject of the email
(because sometimes it is necessary to dynamically insert data into the subject of the email)

The names of these scripts are fixed. It is these files that effectively make up the template itself.

Using a template in an application

The template is used by simply creating an instance of the Jet\Mailing_Email_Template class. Here is a specific practical example of how our sample template is used.


$email_template = new Mailing_Email_Template(

    template_id: 'administrator/user_welcome',

    locale: $this->getLocale()

);



$email_template->setVar( 'user', $this );

$email_template->setVar( 'password', $password );



$email = $email_template->getEmail();





$email->setTo( $this->getEmail() );

$email->send();

The principle is quite simple:

Specify what template you want (what ID)
Optionally, you can specify localisations. Here in the example, it is the localization that is bound to a specific user. Otherwise, the default localization is the current global default.
Optionally, specify the sender ID of the mail.
You pass the necessary data to the template (same principle as for view).
You will get an instance of the email ready to send (to which you can add e.g. attachments - see below).

I highly recommend to get familiar with the Jet\Mailing_Email_Template class in detail. It can not only generate an email, but maybe just display the HTML body of the email. We use this in practice when creating templates, where you can easily implement a preview of the template and a fellow frontend developer doesn't have to send an email every time you modify it.

The email itself and sending it

e-mail

The email itself is represented by the Jet\Mailing_Email class. An instance of this class is the result of generating an email template, but that doesn't mean it can't be used on its own. It is possible, of course, and you can create emails without templates, or create a completely custom system for generating them.

You can see exactly what the class does in its reference. But let's emphasize here that you can do these equally important things with email besides the usual things (specifying HTML form, TXT form ...):

Attach files as attachments.
The email can of course contain images directly (HTML version of the email).
You can specify optional SMTP headers.

Sending email - backend

We have the email already created and ready and now we need to send it. And it's still according to the same principle that applies in Jet in general. That's what the backend is for, which can be replaced. Jet includes a default implementation that you can replace with your own implementation.

The backend is defined by an abstract class Jet\Mailing_Backend_Abstract.

The default backend is Jet\Mailing_Backend_Default

You can replace the backend using the setBackend method of the Jet\Mailing class and get its instance using the getBackend method of the same class.