Email Quick Start
This guide walks you through configuring the email module and sending your first emails.
Step 1: Configure EmailConfig
Add an EmailConfig to your DjangoConfig:
# config.py
from django_cfg import DjangoConfig
from django_cfg.models.services.email import EmailConfig
class MyConfig(DjangoConfig):
project_name = "My Project"
email = EmailConfig(
backend="smtp",
host="smtp.gmail.com",
port=587,
username="${EMAIL_USER}",
password="${EMAIL_PASSWORD}",
use_tls=True,
default_from="[email protected]",
)
admin_emails = ["[email protected]"]For development, use the console backend so emails print to stdout instead of being sent:
email = EmailConfig(backend="console")Step 2: Send Your First Email
from django_cfg import send_email
send_email(
subject="Hello from django-cfg",
message="Your email module is working correctly.",
recipient_list=["[email protected]"],
)The call returns immediately — the email is dispatched in a background thread.
Step 3: Use the Service Class
For HTML and template emails, use DjangoEmailService directly:
from django_cfg.modules.django_email import DjangoEmailService
service = DjangoEmailService()
# Check configuration before sending
if service.is_configured():
service.send_html(
subject="Welcome!",
html_message="<h1>Welcome to My Project</h1><p>Get started today.</p>",
recipient_list=["[email protected]"],
)Step 4: Template Emails
Create templates in your app’s templates/ directory:
templates/
└── emails/
├── welcome.html
└── welcome.txt # optional plain-text alternative<!-- templates/emails/welcome.html -->
<html>
<body>
<h1>Welcome, {{ user_name }}!</h1>
<p>Visit us at <a href="{{ site_url }}">{{ project_name }}</a>.</p>
</body>
</html>Send via template:
service.send_template(
subject="Welcome!",
template_name="emails/welcome", # no extension
context={"user_name": "Jane Doe"},
recipient_list=["[email protected]"],
)project_name, logo_url, and site_url are injected from config automatically if not in context.
Step 5: Admin Notifications
Send alerts to all admin addresses with a single call:
from django_cfg import send_admin_notification
send_admin_notification(
subject="Backup completed",
message="Daily backup finished at 02:00 UTC.",
send_email=True,
send_telegram=True, # also sends to Telegram if configured
)Step 6: Test with the Management Command
Verify your SMTP setup and templates are rendering correctly:
python manage.py test_email --email [email protected] --type allThis sends all built-in template variants (base, otp, welcome, login_alert) to the specified address and prints backend info to stdout.
Next Steps
- Configuration Reference — all
EmailConfigfields, provider-specific setups - Overview — full public API reference and error handling
Django-CFG