dj-email-url

library1.0.6pypypi✓ verified 86d ago

dj-email-url is a Python utility that allows configuring email backend settings in Django applications using a URL, similar to `dj-database-url` for database configurations. It adheres to the 12-factor app principles by enabling email settings to be fetched from an environment variable. The current version is 1.0.6, and it has a steady release cadence with updates addressing Python version compatibility and new features.

web-framework communication

pip install dj-email-url

github ↗package ↗

INSTALL

IMPORT

SIG · DJ-EMAIL-URL

dj-email-url

web-frameworkpythonv1.0.6

Install

1.5s avg

Import

9ms

Disk

16MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.0.6 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.920 runs

installs and imports cleanly · install 0.0s · import 0.010s · 17.8MB

glibc

py 3.10–3.920 runs

installs and imports cleanly · install 1.5s · import 0.007s · 18MB

16MB installed

● package 16MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

dj_email_url

✓ import dj_email_url

To quickly set up `dj-email-url`, import the package in your Django `settings.py` file. It automatically fetches the email configuration from the `EMAIL_URL` environment variable (if available) and applies the extracted settings to Django's email configuration. You can also parse an arbitrary email URL directly. The example demonstrates setting a default 'console:' URL for development and applying the extracted settings to the Django `settings` object. Remember to set the `DJANGO_EMAIL_URL` environment variable in your production environment.

import os from django.conf import settings # Typically, EMAIL_URL would come from an environment variable. # Example: 'smtp://user:password@smtp.example.com:587/?use_tls=True' os.environ['EMAIL_URL'] = os.environ.get('DJANGO_EMAIL_URL', 'console:') # Configure settings from the EMAIL_URL environment variable email_config = dj_email_url.config() # Apply the configurations to Django's EMAIL settings settings.EMAIL_BACKEND = email_config['EMAIL_BACKEND'] settings.EMAIL_HOST = email_config['EMAIL_HOST'] settings.EMAIL_PORT = email_config['EMAIL_PORT'] settings.EMAIL_HOST_USER = email_config['EMAIL_HOST_USER'] settings.EMAIL_HOST_PASSWORD = email_config['EMAIL_HOST_PASSWORD'] settings.EMAIL_USE_TLS = email_config['EMAIL_USE_TLS'] settings.EMAIL_USE_SSL = email_config['EMAIL_USE_SSL'] settings.EMAIL_TIMEOUT = email_config['EMAIL_TIMEOUT'] settings.EMAIL_FILE_PATH = email_config['EMAIL_FILE_PATH'] # Only relevant for file backend # Optional: Set DEFAULT_FROM_EMAIL and SERVER_EMAIL from URL query params or defaults settings.DEFAULT_FROM_EMAIL = email_config.get('DEFAULT_FROM_EMAIL', 'webmaster@localhost') settings.SERVER_EMAIL = email_config.get('SERVER_EMAIL', 'root@localhost') print(f"Email Backend: {settings.EMAIL_BACKEND}") print(f"Email Host: {settings.EMAIL_HOST}") print(f"Email Port: {settings.EMAIL_PORT}") print(f"Default From Email: {settings.DEFAULT_FROM_EMAIL}")

Debug

Known issues

deprecatedThe `smtps` scheme in the email URL is deprecated for indicating TLS connections. It was used to set `EMAIL_USE_TLS = True`.

fix

Use `submission://` or `submit://` schemes for SMTP with STARTTLS on port 587. For SMTP over SSL (port 465), include `?ssl=True` in your URL.

affects: 0.1.0 and later

gotchaSpecial characters in passwords or other URL components must be percent-encoded to avoid parsing errors. This includes characters like '&', '%', '#', etc.

fix

Use `urllib.parse.quote_plus()` to encode passwords and other sensitive URL parts. For example, `m&m` becomes `m%26m` and `%` becomes `%25`.

affects: All versions

gotcha`DEFAULT_FROM_EMAIL` and `SERVER_EMAIL` can be specified as query parameters (`_default_from_email` and `_server_email`) in the `EMAIL_URL`. However, `dj-email-url` only extracts these values; you must explicitly assign them to `settings.DEFAULT_FROM_EMAIL` and `settings.SERVER_EMAIL` in your `settings.py`.

fix

After `email_config = dj_email_url.config()`, ensure you add lines like `settings.DEFAULT_FROM_EMAIL = email_config.get('DEFAULT_FROM_EMAIL', 'webmaster@localhost')` and `settings.SERVER_EMAIL = email_config.get('SERVER_EMAIL', 'root@localhost')`.

affects: 0.2.0 and later

Errors

Common errors & fixes

Email verification links in Django applications are incorrect or broken (e.g., when using `dj-rest-auth`).

While not a direct `dj-email-url` issue, this is often due to misconfigured Django email settings (`EMAIL_HOST`, `EMAIL_PORT`, `EMAIL_USE_TLS/SSL`) or incorrect site domain settings in the Django Sites framework. `dj-email-url` relies on these underlying configurations being correct for the generated URLs.

fix

Ensure your `EMAIL_URL` provides the correct host, port, and security settings for your email service. Also, verify that your Django `SITE_ID` and `django.contrib.sites` configuration accurately reflect your application's domain.

Django admin emails or error reports (e.g., 500 errors) are not being sent, even when `ADMINS` is configured.

This is commonly caused by a missing or invalid `SERVER_EMAIL` setting in Django. Many email servers reject emails from default or suspicious addresses like `root@localhost`, leading to silent failures.

fix

Set `settings.SERVER_EMAIL` to a valid, recognized email address for your domain. You can configure this via the `_server_email` query parameter in your `EMAIL_URL` and then assign it to `settings.SERVER_EMAIL` as shown in the quickstart.

Emails are not being sent at all, or Django reports an `ImproperlyConfigured` error related to email backend.

The `EMAIL_BACKEND` setting in Django is not correctly configured or is missing. While `dj-email-url` provides this value, it must be assigned to the Django `settings.EMAIL_BACKEND`.

fix

Ensure `settings.EMAIL_BACKEND = email_config['EMAIL_BACKEND']` is explicitly set in your `settings.py` after `dj_email_url.config()` is called. Verify that the `EMAIL_URL` scheme corresponds to a valid Django email backend (e.g., `smtp:`, `console:`, `file:`, `memory:`, `dummy:`).

Upgrade

Version history

1.0.6latest on PyPI · released Sep 24, 2022

Audit

Dependencies

No dependency data recorded yet.

Agent activity

15 hits · last 30 days

node

Bingbot

OpenAI (training)

Resources

githubhttps://github.com/migonzalvar/dj-email-url ↗

packagehttps://pypi.org/project/dj-email-url/ ↗