Skip to content
master
Switch branches/tags
Code

Latest commit

 

Git stats

Files

Permalink
Failed to load latest commit information.
Type
Name
Latest commit message
Commit time
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

dj-email-url Latest version on PyPI

Build status codecov Python versions

This utility is based on dj-database-url by Kenneth Reitz.

It allows to utilize the 12factor inspired environments variable to configure the email backend in a Django application.

Usage

Import the package in settings.py:

import dj_email_url

Fetch your email configuration values. The default option is fetch them from EMAIL_URL environment variable:

email_config = dj_email_url.config()

Other option is parse an arbitrary email URL:

email_config = dj_email_url.parse('smtp://...')

Finally, it is necessary to assign values to settings:

EMAIL_FILE_PATH = email_config['EMAIL_FILE_PATH']
EMAIL_HOST_USER = email_config['EMAIL_HOST_USER']
EMAIL_HOST_PASSWORD = email_config['EMAIL_HOST_PASSWORD']
EMAIL_HOST = email_config['EMAIL_HOST']
EMAIL_PORT = email_config['EMAIL_PORT']
EMAIL_BACKEND = email_config['EMAIL_BACKEND']
EMAIL_USE_TLS = email_config['EMAIL_USE_TLS']
EMAIL_USE_SSL = email_config['EMAIL_USE_SSL']

Alternatively, it is possible to use this less explicit shortcut:

vars().update(email_config)

Supported backends

Currently, dj-email-url supports:

Backend EMAIL_URL Description
Console console: Writes to stdout (development)
SMTP smtp: Sends using a mail transfer agent at localhost on port 25
SMTP submission://USER:PASSWORD@smtp.sendgrid.com Sends using SendGrid SMTP on port 587 (STARTTLS)
File file: Writes to a file
In-memory memory:  
Dummy dummy:  

Warning

Using special characters on passwords

To use characters that have a special meaning in an URL (think of &) you should use percent encoding. For example, m&m would become m%26m.

Because the percent character itself (%) serves as the indicator for percent-encoded octets, it must be percent-encoded as %25.

>>> from urllib.parse import quote_plus
>>> import dj_email_url
>>> quote_plus("!@#$%^&*")
'%21%40%23%24%25%5E%26%2A'
>>> dj_email_url.parse("smtp://user:%21%40%23%24%25%5E%26%2A@localhost")["EMAIL_HOST_PASSWORD"]
'!@#$%^&*'

Set from email addresses

dj-email-url also supports to optionally specify origin email addreses.

Setting Query parameter
SERVER_EMAIL _server_email
DEFAULT_FROM_EMAIL _default_from_email

For example: smtp://USER:PASSWORD@smtp.example.com/?_server_email=error@example.com

Do not forget to assign values to settings:

SERVER_EMAIL = email_config.get('SERVER_EMAIL', 'root@localhost')
DEFAULT_FROM_EMAIL = email_config.get('DEFAULT_FROM_EMAIL', 'webmaster@localhost')

More info

SMTP backend

The SMTP backend is selected when the scheme in the URL if one these:

Value Default port Comment
smtp 25 Local mail transfer agent
submission or submit 587 SMTP with STARTTLS

Changed in version 0.1: The use of smtps is now discouraged The value smtps was used to indicate to use TLS connections, that is to set EMAIL_USE_TLS to True. Now is recommended to use submission or submit (see service name for port numbers or Uniform Resource Identifier Schemes at IANA).

On the most popular mail configuration option is to use a third party SMTP server to relay emails.

>>> url = 'submission://user@example.com:pass@smtp.example.com'
>>> url = dj_email_url.parse(url)
>>> assert url['EMAIL_PORT'] == 587
>>> assert url['EMAIL_USE_SSL'] is False
>>> assert url['EMAIL_USE_TLS'] is True

Other common option is to use a local mail transfer agent Postfix or Exim. In this case it as easy as:

>>> url = 'smtp://'
>>> url = dj_email_url.parse(url)
>>> assert url['EMAIL_HOST'] == 'localhost'
>>> assert url['EMAIL_PORT'] == 25
>>> assert url['EMAIL_USE_SSL'] is False
>>> assert url['EMAIL_USE_TLS'] is False

It is also possible to configure SMTP-over-SSL (usually on 465). This configuration is not generally recommended but might be needed for legacy systems. To apply use this configuration specify SSL using a ssl=True as a query parameter and indicate the port explicitly:

>>> url = 'smtp://user@domain.com:pass@smtp.example.com:465/?ssl=True'
>>> url = dj_email_url.parse(url)
>>> assert url['EMAIL_PORT'] == 465
>>> assert url['EMAIL_USE_SSL'] is True
>>> assert url['EMAIL_USE_TLS'] is False

File backend

The file backend is the only one which needs a path. The url path is store in EMAIL_FILE_PATH key.

About

Use an URL to configure email backend settings in your Django Application.

Resources

License

Packages

No packages published