Install & Compatibility
Where this runs
tested against v1.3.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.506s · 85.8MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 4.7s · import 0.482s · 86MB
86MB installed
● package 86MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
SendgridBackend
✓ from sendgrid_backend import SendgridBackend
✗ from django_sendgrid_v5 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.
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}")
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'sendgrid_backend'
This error occurs when the 'django-sendgrid-v5' package is not installed or the EMAIL_BACKEND setting in Django is incorrectly configured, preventing the 'sendgrid_backend' module from being found.
fixFirst, ensure the library is installed: `pip install django-sendgrid-v5`. Then, in your `settings.py`, correctly set the `EMAIL_BACKEND`: `EMAIL_BACKEND = "sendgrid_backend.SendgridBackend"`.
Emails don't get delivered (no exception raised)
Emails may not be delivered silently due to SendGrid's sandbox mode being enabled, preventing actual sending, or issues with SendGrid account configuration like unauthenticated sender identities or incorrect API key permissions.
fix1. In `settings.py`, set `SENDGRID_SANDBOX_MODE_IN_DEBUG = False` (if `DEBUG` is True) or ensure `SENDGRID_SANDBOX_MODE` is not `True` to allow actual email delivery. 2. Verify that your `SENDGRID_API_KEY` is correct and has 'Mail Send' permissions in your SendGrid account. 3. Ensure the 'from' email address used in your Django application is authenticated (either via Domain Authentication or Single Sender Verification) in your SendGrid account.
HTTP Error 400 Bad Request OR HTTP error 403: Forbidden SendGrid
These HTTP errors typically point to problems with the SendGrid API key, such as it being invalid, revoked, having insufficient permissions, or the sender identity not being properly authenticated in SendGrid. A 400 error can also indicate malformed email data.
fix1. Double-check your `SENDGRID_API_KEY` in `settings.py` for accuracy and ensure it's still active and has full 'Mail Send' access in your SendGrid account. 2. Confirm that the sender email address (`DEFAULT_FROM_EMAIL` or the `from_email` used) is verified and authenticated within your SendGrid account. 3. If the key and sender are correct, review the content and structure of the email being sent for any invalid data.
AttributeError: 'SendGridAPIClient' object has no attribute 'send'
This error usually arises from a version mismatch with the underlying `sendgrid-python` library or if `sendgrid-django` (an older, separate package) is installed alongside `django-sendgrid-v5`, leading to API method conflicts when trying to use `SendGridAPIClient.send()`.
fix1. Ensure only `django-sendgrid-v5` is installed and remove any conflicting packages like `sendgrid-django` (`pip uninstall sendgrid-django`). 2. If you are directly calling `sendgrid.SendGridAPIClient` methods, confirm your `sendgrid-python` library version is compatible and that you are using the correct method signature, typically passing a `sendgrid.helpers.mail.Mail` object to `sg.send()`. For `django-sendgrid-v5`, stick to Django's standard `send_mail` or `EmailMessage.send()` functions.
Upgrade
Version history
1.3.1latest on PyPI · released Jan 5, 2026
Audit
Dependencies
DjangorequiredRequired for Django EmailBackend integration. Currently supports Django >= 3.2, < 5.3.
sendgridrequiredCore SendGrid API client. Requires sendgrid >= 5.0.0.