dj-email-url

1.0.6 · active · verified Thu Apr 16

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.

Common errors

```
Email verification links in Django applications are incorrect or broken (e.g., when using `dj-rest-auth`).
```
cause 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.
```
cause 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.
```
cause 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:`).

Warnings

deprecated The `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.
gotcha Special 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`.
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')`.

Install

pip install dj-email-url Install latest version

Imports

dj_email_url
```
import dj_email_url
```

Quickstart

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}")

view raw JSON →