Skip to main content

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

Project description

CI status 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']
EMAIL_TIMEOUT = email_config['EMAIL_TIMEOUT']

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:

Set from email addresses

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

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')

Other settings

There are other settings available to set from query param.

Setting

Query parameter

Comments

EMAIL_TIMEOUT

timeout

New in v1.0.5.

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.

License

This work is licensed under several licences.

  • All original source code is licensed under BSD-2-Clause.

  • All documentation is licensed under CC-BY-4.0.

  • Some configuration and data files are licensed under CC0-1.0.

For more accurate information, check the individual files.

You can check the compliance with REUSE helper tool.

Change Log

Unreleased

1.0.6 - 2022-09-24

  • Remove unnecessary code (thanks @matthiask).

  • Improve license metadata. No changes on license itself.

1.0.5 - 2022-02-05

  • Added support for the timeout setting.

1.0.4 - 2022-01-16

  • Post release version to update change log.

1.0.3 - 2022-01-16

  • Added support for Python 3.10.

  • Changed continuos integration infrastructure from Travis to GitHub Actions.

  • Switched to PyPA build frontend.

1.0.2 - 2021-01-23

  • Add support for Python 3.9 (@pauloxnet)

1.0.1 - 2020-06-03

  • Included LICENSE file in tarball. Thanks to @fabaff.

1.0.0 - 2020-02-16

  • Removed support for Python versions which reached end-of-life.

  • Fixed typo. Thanks to @jeffmacdonald.

0.2.0 - 2019-04-08

  • Added support for DEFAULT_FROM_EMAIL and SERVER_EMAIL in the URL as query parameters.

0.1.0 - 2018-03-24

  • Added new schemes submission and submit to select SMTP backend on port 587 with STARTTLS. Thanks to @LEW21 to suggest to include new submit URI.

  • Discouraged the use of scheme smtps and add a user warning. Thanks to @LEW21 to alert about this confusing usage.

  • Expand which values are considered as truthy on a query string param. Now, 1, on, true, and yes, as a single character or in all case variants (lower, upper and title case) are considered as True.

0.0.10 - 2016-10-14

  • Post release version to fix release date in change log.

0.0.9 - 2016-10-14

  • Fix case when user sets ssl=False in its url (thanks bogdal)

0.0.8 - 2016-06-07

  • Allow universal wheel

0.0.7 - 2016-05-31

  • Add EMAIL_USE_SSL setting to docs and set a default value (thanks iraycd).

  • Add coverage (thanks iraycd).

0.0.6 - 2016-04-18

  • Fix error parsing URL without credentials (thanks martinmaillard).

0.0.5 - 2016-04-17

  • Allow URL encoded credentials (thanks kane-c).

0.0.4 - 2015-03-05

  • Fix README.

0.0.3 - 2015-03-05

  • Add change log.

  • Add ssl= option as a query parameter for SMTP backend.

  • Add Travis continuous integration.

0.0.2 - 2014-03-12

  • Add Python 3 support.

0.0.1 - 2013-02-12

  • Initial version.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

dj-email-url-1.0.6.tar.gz (15.6 kB view details)

Uploaded Source

Built Distribution

dj_email_url-1.0.6-py2.py3-none-any.whl (6.3 kB view details)

Uploaded Python 2 Python 3

File details

Details for the file dj-email-url-1.0.6.tar.gz.

File metadata

  • Download URL: dj-email-url-1.0.6.tar.gz
  • Upload date:
  • Size: 15.6 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/4.0.1 CPython/3.10.6

File hashes

Hashes for dj-email-url-1.0.6.tar.gz
Algorithm Hash digest
SHA256 55ffe3329e48f54f8a75aa36ece08f365e09d61f8a209773ef09a1d4760e699a
MD5 4005c75282a07cde7aac787ed51277df
BLAKE2b-256 14ef8eb478accd9b0369d46a98d1b43027ee0c254096149265c78e6b2e2fa3b0

See more details on using hashes here.

Provenance

File details

Details for the file dj_email_url-1.0.6-py2.py3-none-any.whl.

File metadata

File hashes

Hashes for dj_email_url-1.0.6-py2.py3-none-any.whl
Algorithm Hash digest
SHA256 cbd08327fbb08b104eac160fb4703f375532e4c0243eb230f5b960daee7a96db
MD5 4fbeecbae967a325291aa0e8692efd96
BLAKE2b-256 8af9fcb9745099d821f9a26092d3d6f4df8f10049885045c3a93ff726d2e40a6

See more details on using hashes here.

Provenance

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page