{"id":8085,"library":"dj-email-url","title":"dj-email-url","description":"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.","status":"active","version":"1.0.6","language":"en","source_language":"en","source_url":"https://github.com/migonzalvar/dj-email-url","tags":["django","email","configuration","12factor","environment-variables"],"install":[{"cmd":"pip install dj-email-url","lang":"bash","label":"Install latest version"}],"dependencies":[],"imports":[{"symbol":"dj_email_url","correct":"import dj_email_url"}],"quickstart":{"code":"import os\nfrom django.conf import settings\n\n# Typically, EMAIL_URL would come from an environment variable.\n# Example: 'smtp://user:password@smtp.example.com:587/?use_tls=True'\nos.environ['EMAIL_URL'] = os.environ.get('DJANGO_EMAIL_URL', 'console:')\n\n# Configure settings from the EMAIL_URL environment variable\nemail_config = dj_email_url.config()\n\n# Apply the configurations to Django's EMAIL settings\nsettings.EMAIL_BACKEND = email_config['EMAIL_BACKEND']\nsettings.EMAIL_HOST = email_config['EMAIL_HOST']\nsettings.EMAIL_PORT = email_config['EMAIL_PORT']\nsettings.EMAIL_HOST_USER = email_config['EMAIL_HOST_USER']\nsettings.EMAIL_HOST_PASSWORD = email_config['EMAIL_HOST_PASSWORD']\nsettings.EMAIL_USE_TLS = email_config['EMAIL_USE_TLS']\nsettings.EMAIL_USE_SSL = email_config['EMAIL_USE_SSL']\nsettings.EMAIL_TIMEOUT = email_config['EMAIL_TIMEOUT']\nsettings.EMAIL_FILE_PATH = email_config['EMAIL_FILE_PATH'] # Only relevant for file backend\n\n# Optional: Set DEFAULT_FROM_EMAIL and SERVER_EMAIL from URL query params or defaults\nsettings.DEFAULT_FROM_EMAIL = email_config.get('DEFAULT_FROM_EMAIL', 'webmaster@localhost')\nsettings.SERVER_EMAIL = email_config.get('SERVER_EMAIL', 'root@localhost')\n\nprint(f\"Email Backend: {settings.EMAIL_BACKEND}\")\nprint(f\"Email Host: {settings.EMAIL_HOST}\")\nprint(f\"Email Port: {settings.EMAIL_PORT}\")\nprint(f\"Default From Email: {settings.DEFAULT_FROM_EMAIL}\")\n","lang":"python","description":"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."},"warnings":[{"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.","message":"The `smtps` scheme in the email URL is deprecated for indicating TLS connections. It was used to set `EMAIL_USE_TLS = True`.","severity":"deprecated","affected_versions":"0.1.0 and later"},{"fix":"Use `urllib.parse.quote_plus()` to encode passwords and other sensitive URL parts. For example, `m&m` becomes `m%26m` and `%` becomes `%25`.","message":"Special characters in passwords or other URL components must be percent-encoded to avoid parsing errors. This includes characters like '&', '%', '#', etc.","severity":"gotcha","affected_versions":"All versions"},{"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')`.","message":"`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`.","severity":"gotcha","affected_versions":"0.2.0 and later"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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.","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.","error":"Email verification links in Django applications are incorrect or broken (e.g., when using `dj-rest-auth`)."},{"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.","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.","error":"Django admin emails or error reports (e.g., 500 errors) are not being sent, even when `ADMINS` is configured."},{"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:`).","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`.","error":"Emails are not being sent at all, or Django reports an `ImproperlyConfigured` error related to email backend."}]}