Welcome to django-mail-factory’s documentation!

Django Mail Factory is a little Django app that let’s you manage emails for your project very easily.


Django Mail Factory has support for:

  • Multilingual
  • Administration to preview or render emails
  • Multi-alternatives emails: text and html
  • Attachments
  • HTML inline display of attached images

Get started

From PyPI:

pip install django-mail-factory

From the github tree:

pip install -e http://github.com/peopledoc/django-mail-factory/

Then add mail_factory to your INSTALLED_APPS:


Create your first mail


from mail_factory import factory
from mail_factory.mails import BaseMail

class WelcomeEmail(BaseMail):
    template_name = 'activation_email'
    params = ['user', 'site_name', 'site_url']


Then you must also create the templates:

  • templates/mails/activation_email/subject.txt
[{{site_name }}] Dear {{ user.first_name }}, your account is created
  • templates/mails/activation_email/body.txt
Dear {{ user.first_name }},

Your account has been created for the site {{ site_name }}, and is
available at {{ site_url }}.

See you there soon!

The awesome {{ site_name }} team
  • templates/mails/activation_email/body.html (optional)

Send a mail

Using the factory:

from mail_factory import factory

factory.mail('activation_email', [user.email],
             {'user': user,
              'site_name': settings.SITE_NAME,
              'site_url': settings.SITE_URL})

Using the mail class:

from my_app.mails import WelcomeEmail

msg = WelcomeEmail({'user': user,
                    'site_name': settings.SITE_NAME,
                    'site_url': settings.SITE_URL})

How does it work?

At startup, all mails.py files in your application folders are automatically discovered and the emails are registered to the factory.

You can then directly call your emails from the factory with their template_name.

It also allows you to list your emails in the administration, preview and test them by sending them to a custom address with a custom context.


mail_factory automatically performs autodiscovery of mails modules in installed applications. To prevent it, change your INSTALLED_APPS to contain ‘mail_factory.SimpleMailFactoryConfig’ instead of ‘mail_factory’.

This is only available in Django 1.7 and above.