0
# Django SendGrid v5
1
2
A Django email backend implementation that integrates with SendGrid's REST API v5+ for reliable email delivery. This package provides seamless email sending functionality through Django's standard email API while offering advanced SendGrid-specific features like dynamic templates, personalization, webhook signature verification, tracking, and scheduling.
3
4
## Package Information
5
6
- **Package Name**: django-sendgrid-v5
7
- **Language**: Python
8
- **Installation**: `pip install django-sendgrid-v5`
9
10
## Core Imports
11
12
```python
13
from sendgrid_backend import SendgridBackend, __version__
14
```
15
16
For Django settings integration:
17
18
```python
19
# In settings.py
20
EMAIL_BACKEND = "sendgrid_backend.SendgridBackend"
21
SENDGRID_API_KEY = "your-sendgrid-api-key"
22
```
23
24
## Basic Usage
25
26
```python
27
from django.core.mail import send_mail, EmailMessage
28
29
# Simple email sending using Django's standard API
30
send_mail(
31
'Subject here',
32
'Here is the message.',
33
'from@example.com',
34
['to@example.com'],
35
fail_silently=False,
36
)
37
38
# Enhanced email with SendGrid-specific features
39
msg = EmailMessage(
40
subject='Advanced Email',
41
body='Email content',
42
from_email='sender@example.com',
43
to=['recipient@example.com'],
44
)
45
46
# Add SendGrid-specific attributes
47
msg.template_id = "d-abc123def456"
48
msg.dynamic_template_data = {"name": "John", "product": "Widget"}
49
msg.categories = ["marketing", "newsletter"]
50
msg.send()
51
```
52
53
## Architecture
54
55
The package extends Django's BaseEmailBackend with SendGrid API integration:
56
57
- **SendgridBackend**: Main email backend class that translates Django EmailMessage objects to SendGrid API calls
58
- **Django Settings Integration**: Seamless configuration through Django settings for API keys, tracking, and sandbox mode
59
- **Version Compatibility**: Automatic detection and support for both SendGrid API v5 and v6 with internal compatibility handling
60
- **Signal System**: Django signal emission for email delivery events with success/failure tracking
61
- **Webhook Security**: Cryptographic signature verification for SendGrid webhook endpoints
62
63
## Capabilities
64
65
### Email Backend
66
67
The core SendGrid email backend implementation that replaces Django's default email backend with SendGrid API integration.
68
69
```python { .api }
70
class SendgridBackend(BaseEmailBackend):
71
def __init__(self, *args, **kwargs): ...
72
def send_messages(self, email_messages) -> int: ...
73
def echo_to_output_stream(self, email_messages): ...
74
```
75
76
[Email Backend](./email-backend.md)
77
78
### Template and Personalization
79
80
Dynamic template support with variable substitution and personalized content for individual recipients.
81
82
```python { .api }
83
# EmailMessage extensions for templates
84
msg.template_id = "template-id"
85
msg.dynamic_template_data = dict # v6+
86
msg.substitutions = dict # v5
87
msg.personalizations = list # Advanced personalization
88
```
89
90
[Templates and Personalization](./templates-personalization.md)
91
92
### Configuration and Settings
93
94
Django settings integration for API keys, tracking options, sandbox mode, and other SendGrid-specific configurations.
95
96
```python { .api }
97
# Django settings
98
SENDGRID_API_KEY = str
99
SENDGRID_SANDBOX_MODE_IN_DEBUG = bool
100
SENDGRID_TRACK_EMAIL_OPENS = bool
101
SENDGRID_TRACK_CLICKS_HTML = bool
102
SENDGRID_TRACK_CLICKS_PLAIN = bool
103
```
104
105
[Configuration](./configuration.md)
106
107
### Webhook Integration
108
109
Secure webhook handling with signature verification for processing SendGrid delivery events and email tracking data.
110
111
```python { .api }
112
@verify_sendgrid_webhook_signature
113
def webhook_handler(request): ...
114
115
def check_sendgrid_signature(request) -> bool: ...
116
```
117
118
[Webhooks](./webhooks.md)
119
120
### Signals and Events
121
122
Django signal system for handling email delivery events, enabling custom logging, analytics, and error handling.
123
124
```python { .api }
125
sendgrid_email_sent = django.dispatch.Signal()
126
# Signal arguments: sender, message, fail_flag
127
```
128
129
[Signals](./signals.md)
130
131
## Types
132
133
```python { .api }
134
# Package version
135
__version__: str # Package version string (e.g., "1.3.0")
136
137
# Email message extensions
138
class EmailMessage:
139
# Template support
140
template_id: str
141
dynamic_template_data: dict # v6+
142
substitutions: dict # v5
143
144
# Personalization
145
personalizations: list
146
make_private: bool
147
custom_args: dict
148
149
# Scheduling and delivery
150
send_at: int # Unix timestamp
151
ip_pool_name: str
152
153
# Organization and tracking
154
categories: list[str]
155
asm: dict # Unsubscribe groups
156
reply_to_list: list[str] # v6+
157
158
# Advanced settings
159
mail_settings: MailSettings
160
tracking_settings: TrackingSettings
161
```