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.
Import the package in
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:
Currently, dj-email-url supports:
||Writes to stdout (development)|
||Sends using a mail transfer agent at localhost on port 25|
||Sends using SendGrid SMTP on port 587 (STARTTLS)|
||Writes to a file|
Using special characters on passwords
To use characters that have a special meaning in an URL (think of
you should use percent encoding.
m&m would become
Because the percent character itself (
%) serves as the indicator for
percent-encoded octets, it must be percent-encoded as
>>> 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.
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')
The SMTP backend is selected when the scheme in the URL if one these:
||25||Local mail transfer agent|
||587||SMTP with STARTTLS|
Changed in version 0.1: The use of
smtps is now discouraged
smtps was used to indicate to use TLS connections,
that is to set
Now is recommended to use
(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://firstname.lastname@example.org:email@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://firstname.lastname@example.org:email@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
The file backend is the only one which needs a path. The url path is store