Django SendGrid v5 Backend

Warnings

• breaking Python 2 support was dropped entirely in version 1.0.0. Projects using older Python versions must upgrade Python before upgrading to `django-sendgrid-v5` v1.0.0 or later.
  Fix: Upgrade your Python environment to Python 3.6 or newer. (Currently supports Python >=3.8)
• breaking Version 1.3.0 and 1.3.1 dropped support for several older Python and Django versions. Specifically, v1.3.1 dropped support for Django 5.0, now requiring Django 5.2 or later for Django 5.x series.
  Fix: Ensure your project runs on supported Python and Django versions (e.g., Python >=3.8, Django >=3.2, <5.3). Review the project's pyproject.toml for exact version constraints.
• gotcha The `EMAIL_BACKEND` setting in Django must be correctly configured to point to `sendgrid_backend.SendgridBackend` for the library to be used.
  Fix: In your Django `settings.py`, ensure `EMAIL_BACKEND = 'sendgrid_backend.SendgridBackend'` is set.
• gotcha The `SENDGRID_API_KEY` must be provided in your Django settings, typically via an environment variable, for authentication with SendGrid.
  Fix: Set `SENDGRID_API_KEY = os.environ.get('SENDGRID_API_KEY', 'your_fallback_key')` in your `settings.py`.
• gotcha The `from_email` specified in `send_mail` or `EmailMessage` must be a sender email address verified in your SendGrid account, or emails will fail.
  Fix: Verify the sender email address(es) in your SendGrid dashboard.

Install

• pip install django-sendgrid-v5 Install stable version

Imports

• SendgridBackend
  wrong:

  from django_sendgrid_v5 import SendgridBackend

  correct:

  from sendgrid_backend import SendgridBackend

  The top-level package for the backend is `sendgrid_backend`, not `django_sendgrid_v5`.
• verify_sendgrid_webhook_signature

  from sendgrid_backend.utils import verify_sendgrid_webhook_signature

  Introduced in v1.3.0 for easier webhook development.

Quickstart

Configure `EMAIL_BACKEND` and `SENDGRID_API_KEY` in your Django `settings.py`. Then use Django's standard `send_mail` or `EmailMessage` functions to send emails. Ensure `SENDGRID_API_KEY` is set as an environment variable or directly in settings. `SENDGRID_SANDBOX_MODE = True` can be used for testing without consuming SendGrid credits.

import os
from django.core.mail import send_mail, EmailMessage
from django.conf import settings

# --- Minimal Django settings configuration for demonstration ---
# In a real Django project, these would be in your settings.py
# and Django's settings would already be configured.
if not settings.configured:
    settings.configure(
        EMAIL_BACKEND='sendgrid_backend.SendgridBackend',
        SENDGRID_API_KEY=os.environ.get('SENDGRID_API_KEY', 'DUMMY_SENDGRID_API_KEY'),
        # Optional: Set sandbox mode for testing without sending real emails
        # SENDGRID_SANDBOX_MODE=True,
        DEBUG=True # Required for settings.configure
    )

print(f"Using SendGrid API Key: {settings.SENDGRID_API_KEY[:5]}... (first 5 chars)")

# --- Sending a basic email ---
try:
    send_mail(
        'Hello from Django SendGrid!',
        'This is a test email sent via SendGrid.',
        'from@example.com', # Must be a verified sender in SendGrid
        ['to@example.com'],
        fail_silently=False,
    )
    print("Basic email sent successfully (or attempted if in sandbox).")
except Exception as e:
    print(f"Error sending basic email: {e}")

# --- Sending an email with more options using EmailMessage ---
try:
    email = EmailMessage(
        'Advanced Django SendGrid Email',
        'This email uses EmailMessage for more control.',
        'from@example.com',
        ['to@example.com'],
        reply_to=['reply@example.com'],
        headers={'X-Custom-Header': 'My-Value'},
    )
    # Example of adding a personalization (requires sendgrid.Personalization object or dict)
    # from sendgrid.helpers.mail import Personalization, Email
    # p = Personalization()
    # p.add_to(Email('another_recipient@example.com'))
    # email.personalizations = [p]

    # Example of using a SendGrid Dynamic Template
    # email.template_id = 'd-xxxxxxxxxxxxxxxxxxxxxxx'
    # email.dynamic_template_data = {'name': 'User', 'message': 'Welcome!'}

    email.send(fail_silently=False)
    print("Advanced email sent successfully (or attempted if in sandbox).")
except Exception as e:
    print(f"Error sending advanced email: {e}")