Django Celery Email

Common errors

• ModuleNotFoundError: No module named 'celery'

  cause Celery is not installed or not available in the Python environment where django-celery-email is running.
  fix Install Celery: `pip install celery` (and optionally a broker like `pip install redis`).

• RuntimeError: No application found. You did not specify an application.

  cause This error typically indicates that your Celery application is not correctly defined or discovered, or the Celery worker was started without pointing to your Django project.
  fix Ensure you have a `celery.py` file in your Django project, and start your Celery worker from your project root: `celery -A your_project_name worker -l info`.

• Emails are not sending, or tasks are stuck in 'PENDING' state.

  cause The Celery worker is not running, is misconfigured, or cannot connect to the broker.
  fix Verify your Celery worker is running (`celery -A your_project_name worker -l info`). Check Celery broker configuration (`CELERY_BROKER_URL`) and ensure the broker service (e.g., Redis server) is running and accessible.

Warnings

• breaking Version 3.0.0 drops support for older Django and Python versions. Django < 3.2 and Python < 3.8 are no longer supported.
  Fix: Upgrade your Django installation to 3.2 or higher and Python to 3.8 or higher before upgrading to django-celery-email 3.x.
• breaking The `recipient_list_split_size` option and related logic have been removed in version 3.0.0. Task arguments have been simplified.
  Fix: Remove `recipient_list_split_size` from your `CELERY_EMAIL_TASK_CONFIG` or any custom task configurations. Adapt any custom task definitions to the new simplified arguments.
• gotcha django-celery-email requires a fully configured and running Celery setup (broker, result backend, and worker process). It only provides the Django email backend interface, not the Celery infrastructure itself.
  Fix: Ensure you have Celery and a broker (e.g., Redis, RabbitMQ) properly installed and configured in your Django project, and that your Celery worker process is running and accessible.
• gotcha By default, `CELERY_EMAIL_BACKEND` uses Django's built-in `django.core.mail.backends.smtp.EmailBackend`. If you use a different default backend (e.g., a service-specific backend like SendGrid, Mailgun), you must explicitly configure it.
  Fix: Set `CELERY_EMAIL_BACKEND = 'your.custom.email.backend.Path'` in your `settings.py` if you need Celery to use a specific non-default email backend.

Install

• pip install django-celery-email Install package

Imports

• CeleryEmailBackend

  from django_celery_email.backends import CeleryEmailBackend

Quickstart

To use django-celery-email, first ensure Celery and its broker (e.g., Redis) are installed and configured. Then, add 'django_celery_email' to `INSTALLED_APPS` and set `EMAIL_BACKEND` in your Django settings to `django_celery_email.backends.CeleryEmailBackend`. Emails sent via `django.core.mail.send_mail` or similar will then be processed asynchronously by Celery workers.

# settings.py

INSTALLED_APPS = [
    # ...
    'django_celery_email',
    # ...
]

# Configure Celery (e.g., using Redis as a broker)
CELERY_BROKER_URL = os.environ.get('CELERY_BROKER_URL', 'redis://localhost:6379/0')

# Point Django to use CeleryEmailBackend
EMAIL_BACKEND = 'django_celery_email.backends.CeleryEmailBackend'

# Optionally, specify the actual backend Celery should use to send emails
# Defaults to 'django.core.mail.backends.smtp.EmailBackend'
# CELERY_EMAIL_BACKEND = 'django.core.mail.backends.smtp.EmailBackend'

# Optional: Configure Celery task options
CELERY_EMAIL_TASK_CONFIG = {
    'queue': 'celery_email',
    'rate_limit': '50/m',
}

# Example usage in an app (e.g., views.py)
from django.core.mail import send_mail

def my_view(request):
    send_mail(
        'Subject here',
        'Here is the message.',
        'from@example.com',
        ['to@example.com'],
        fail_silently=False,
    )
    return HttpResponse('Email scheduled!')