Email

Introduction

Masonite comes with email support out of the box. Most applications will need to send email upon actions like account creation or notifications. Because email is used so often with software applications, masonite provides mail support with several drivers.

Getting Started

All mail configuration is inside config/mail.py and contains several well documented options. There are several built in drivers you can use but you can make your own if you'd like. You can follow the documentation here at Creating a Mail Driver. If you do make your own, consider making it available on PyPi so others can install it. We may even put it in Masonite by default.

By default, Masonite uses the smtp driver. Inside your .env file, just put your smtp credentials. If you are using Mailgun then switch your driver to mailgun and put your Mailgun credentials in your .env file.

Configuring Drivers

There are two drivers out of the box that masonite uses and there is a tiny bit of configuration for both.

SMTP Driver

The SMTP driver takes several configuration files we can all put in our .env file.

MAIL_DRIVER=smtp
MAIL_FROM_ADDRESS=admin@email.com
MAIL_FROM_NAME=Masonite
MAIL_HOST=smtp.gmail.com
MAIL_PORT=465
MAIL_USERNAME=admin@email.com
MAIL_PASSWORD=password

Because this is SMTP, we can utilize all SMTP services such as mailtrap and gmail.

Thats it! As long as the authentication works, we can send emails. Remember that it is save to put sensitive data in your .env file because it is not committed to source control and it is inside the .gitignore file by default.

Mailgun Driver

Mailgun does not use SMTP and instead uses API calls to their service to send emails. Mailgun only requires 2 configuration settings:

MAIL_DRIVER=mailgun
MAILGUN_SECRET=key-xx
MAILGUN_DOMAIN=sandboxXX.mailgun.org

as well as changing the DRIVER inside config/mail.py

DRIVER = 'mailgun'

Masonite will retrieve the configuration settings for the mailgun driver from the DRIVERS configuration setting which Masonite has by default, you do not have to change this.

DRIVERS = {
    ...
    'mailgun': {
        'secret': os.getenv('MAILGUN_SECRET', 'key-XX'),
        'domain': os.getenv('MAILGUN_DOMAIN', 'sandboxXX.mailgun.org')
    }
}

Sending an Email

The Mail class is loaded into the container via the the MailProvider Service Provider. We can fetch this Mail class via our controller methods:

def show(self, Mail):
    print(Mail) # returns the default mail driver

We can send an email like so:

def show(self, Mail):
    Mail.to('hello@email.com').send('Welcome!')

All mail drivers are managed by the MailManager class and bootstrapped with the MailProvider Service Provider. Let's take a look at that:

class MailProvider(ServiceProvider):

wsgi = False

def register(self):
    self.app.bind('MailConfig', mail)
    self.app.bind('MailSmtpDriver', MailSmtpDriver)
    self.app.bind('MailMailgunDriver', MailMailgunDriver)
    self.app.bind('MailManager', MailManager(self.app))

def boot(self, MailConfig):
    self.app.bind('Mail',     MailManager(self.app).driver(MailConfig.DRIVER))

We can specify which driver we want to use. Although Masonite will use the DRIVER variable in our mail config file by default, we can change the driver on the fly.

You can see in our MailProvider Service Provider that we can use the MailManager class to set the driver. We can use this same class to change the driver:

def show(self, MailManager):
    MailManager.driver('mailgun') # now uses the Mailgun driver

Queues

Sending an email may take several seconds so it might be a good idea to create a Job. Jobs are simply Python classes that inherit from the Queueable class and can be pushed to queues or ran asynchronously. This will look something like:

from app.jobs.SendWelcomeEmail import SendWelcomeEmail

def show(self, Queue):
    Queue.push(SendWelcomeEmail)

Instead of taking seconds to send an email, this will seem immediate and be sent using whatever queue driver is set. The async driver is set by default which requires no additional configuration and simply sends jobs into a new thread to be ran in the background.

Read more about creating Jobs and sending emails asynchronously in the "Queues and Jobs" documentation.

Methods

We can specify which driver we want to use. Although Masonite will use the DRIVER variable in our config file, we can change the driver on the fly.

We can also specify the subject:

Mail.subject('Welcome!').to('hello@email.com').send('Welcome!')

You can specify which address you want the email to appear from:

Mail.send_from('Admin@email.com').to('hello@email.com').send('Welcome!')

Templates

If you don't want to pass a string as the message, you can pass a view template.

Mail.to('idmann509@gmail.com').template('mail/welcome').send()

This will render the view into a message body and send the email as html. Notice that we didn't pass anything into the send message

Creating a Mail Driver

Introduction

Because of Masonite's Service Container, It is extremely easy to make drivers that can be used by simply adding your service provider.

Getting Started

Masonite comes shipped with a Service Provider called MailProvider which loads a few classes into the container as well as boots the default mail driver using the MailManager. This manager class will fetch drivers from the container and instantiate them. We can look at the MailProvider class which will gives us a better explanation as to what's going on:

class MailProvider(ServiceProvider):

    wsgi = False

    def register(self):
        self.app.bind('MailConfig', mail)
        self.app.bind('MailSmtpDriver', MailSmtpDriver)
        self.app.bind('MailMailgunDriver', MailMailgunDriver)

    def boot(self):
        self.app.bind('Mail', MailManager(self.app))

We can see here that because we are only binding things into the container and we don't need the WSGI server to be running, we set wsgi = False. Service Providers that set wsgi to False will only run when the server starts and not on every request.

We can see here that we are binding a few drivers into the container and then binding the MailManager on boot. Remember that our boot method has access to everything that has been registered into the container. The register methods are executed on all providers before the boot methods are executed.

Mail Manager

The MailManager here is important to understand. When the MailManager is instantiated, it accepts the container as a parameter. When the MailManager is instantiated, it fires a create_driver method which will grab the driver from the configuration file and retrieve a MailXDriver from the container. The create_driver method is a very simple method:

def create_driver(self, driver=None):
    if not driver:
        driver = self.container.make('MailConfig').DRIVER.capitalize()
    else:
        driver = driver.capitalize()

    try:
        self.manage_driver = self.container.make('Mail{0}Driver'.format(driver))
    except KeyError:
        raise DriverNotFound('Could not find the Mail{0}Driver from the service container. Are you missing a service provider?'.format(driver))

Notice that when the driver is created, it tries to get a Mail{0}Driver from the container. Therefore, all we need to do is register a MailXDriver into the container ('X' being the name of the driver) and Masonite will know to grab that driver.

Creating a Driver

So now we know that we need a MailXDriver so let's walk through how we could create a maildrill email driver.

We can simply create a class which can become our driver. We do not need to inherit anything, although Masonite comes with a BaseMailDriver to get you started faster and all drivers should inherit from it for consistency reasons. You can make your driver from a normal class object but it will be harder and won't be considered in Pull Requests.

Let's create a class anywhere we like and inherit from BaseMailDriver:

from masonite.driver.BaseMailDriver import BaseMailDriver

class MailMaildrillDriver(BaseMailDriver):
    pass

Great! We are almost done. We just have to implement one method on this class and that's the send method. All other methods like to and template are inherited from the BaseMailDriver class. You can find out how to send an email using Maildrill and implement it in this send method.

We can look at other drivers for inspiration but let's look at the MailMailgunDriver class now:

import requests
from masonite.drivers.BaseMailDriver import BaseMailDriver

class MailMailgunDriver(BaseMailDriver):

    def send(self, message=None):
        if not message:
            message = self.message_body

        domain = self.config.DRIVERS['mailgun']['domain']
        secret = self.config.DRIVERS['mailgun']['secret']
        return requests.post(
            "https://api.mailgun.net/v3/{0}/messages".format(domain),
            auth=("api", secret),
            data={"from": "{0} <mailgun@{1}>".format(self.config.FROM['name'], domain),
                  "to": [self.to_address, "{0}".format(self.config.FROM['address'])],
                "subject": self.message_subject,
                "html": message})

If you are wondering where the self.message_body and self.config are coming from, check the BaseMailDriver. All driver constructors are resolved by the service container so you can grab anything you need from the container to make your driver work. Notice here that we don't need a constructor because we inherited it from the BaseMailDriver

Registering Your Mail Driver

Since the MailManager class creates the driver on boot, we can simply register the driver into the container via any service providers register method. We could create a new Service Provider and register it there. You can read more about created Service Providers under the Service Providers documentation. For now, we will just register it from within our AppProvider.

Our AppProvider class might look something like this:

from your.driver.module import MailMandrillDriver
class AppProvider(ServiceProvider):

    wsgi = True

    def register(self):
        self.app.bind('WebRoutes', web.ROUTES)
        self.app.bind('ApiRoutes', api.ROUTES)
        self.app.bind('Response', None)
        self.app.bind('Storage', storage)

        # Register new mail driver
        self.app.bind('MailMandrillDriver', MailMandrillDriver)

    def boot(self, Environ):
        self.app.bind('Request', Request(Environ))
        self.app.bind('Route', Route(Environ))

Great! Our new driver is registered into the container. It is now able to be created with Masonite's MailManager class. We can retrieve your new driver by doing:

def show(self, Mail)
    Mail.driver('mandrill') # fetches MailMandrillDriver from container

Configuration

If we want the MailManager to use our new driver by default, change the DRIVER in our config/mail.py file. In addition, you may have the users of your driver require a special dictionary entry to the DRIVERS dictionary:

DRIVERS = {
    'smtp': {
        'host': os.getenv('MAIL_HOST', 'smtp.mailtrap.io'),
        'port': os.getenv('MAIL_PORT', '465'),
        'username': os.getenv('MAIL_USERNAME', 'username'),
        'password': os.getenv('MAIL_PASSWORD', 'password'),
    },
    'mailgun': {
        'secret': os.getenv('MAILGUN_SECRET', 'key-XX'),
        'domain': os.getenv('MAILGUN_DOMAIN', 'sandboxXX.mailgun.org')
    },
    'maildrill': {
        'secret': 'xx'
        'other_key': 'xx'
    }
}

This way, users can easily swap drivers by simply changing the driver in the config file.

That's it! We just extended our Masonite project and created a new driver. Consider making it available on PyPi so others can install it!