mirror of
https://github.com/pacnpal/django-anymail.git
synced 2025-12-20 03:41:05 -05:00
SendGrid: drop deprecated sendgrid_v2 EmailBackend
This commit is contained in:
medmunds
@@ -5,11 +5,6 @@ SendGrid
|
||||
|
||||
Anymail integrates with the `SendGrid`_ email service, using their `Web API v3`_.
|
||||
|
||||
.. versionchanged:: 0.8
|
||||
|
||||
Earlier Anymail releases used SendGrid's v2 API. If you are upgrading,
|
||||
please review the :ref:`porting notes <sendgrid-v3-upgrade>`.
|
||||
|
||||
.. important::
|
||||
|
||||
**Troubleshooting:**
|
||||
@@ -188,8 +183,7 @@ Limitations and quirks
|
||||
isn't present.)
|
||||
|
||||
**Single Reply-To**
|
||||
SendGrid's v3 API only supports a single Reply-To address (and blocks
|
||||
a workaround that was possible with the v2 API).
|
||||
SendGrid's v3 API only supports a single Reply-To address.
|
||||
|
||||
If your message has multiple reply addresses, you'll get an
|
||||
:exc:`~anymail.exceptions.AnymailUnsupportedFeature` error---or
|
||||
@@ -344,185 +338,3 @@ digests). But disabling it *may* use less memory while processing messages with
|
||||
|
||||
.. _Inbound Parse Webhook:
|
||||
https://sendgrid.com/docs/Classroom/Basics/Inbound_Parse_Webhook/setting_up_the_inbound_parse_webhook.html
|
||||
|
||||
|
||||
.. _sendgrid-v3-upgrade:
|
||||
|
||||
Upgrading to SendGrid's v3 API
|
||||
------------------------------
|
||||
|
||||
Anymail v0.8 switched to SendGrid's preferred v3 send API.
|
||||
(Earlier Anymail releases used their v2 API.)
|
||||
|
||||
For many Anymail projects, this change will be entirely transparent.
|
||||
(Anymail's whole reason for existence is abstracting ESP APIs,
|
||||
so that your own code doesn't need to worry about the details.)
|
||||
|
||||
There are three cases where SendGrid has changed features
|
||||
that would require updates to your code:
|
||||
|
||||
1. If you are using SendGrid's username/password auth (your settings
|
||||
include :setting:`SENDGRID_USERNAME <ANYMAIL_SENDGRID_USERNAME>`
|
||||
and :setting:`SENDGRID_PASSWORD <ANYMAIL_SENDGRID_PASSWORD>`),
|
||||
you must switch to an API key.
|
||||
See :setting:`SENDGRID_API_KEY <ANYMAIL_SENDGRID_API_KEY>`.
|
||||
|
||||
(If you are already using a SendGrid API key with v2, it should
|
||||
work just fine with v3.)
|
||||
|
||||
2. If you are using Anymail's
|
||||
:attr:`~anymail.message.AnymailMessage.esp_extra` attribute
|
||||
to supply API-specific parameters, the format has changed.
|
||||
|
||||
Search your code for "esp_extra" (e.g., `git grep esp_extra`)
|
||||
to determine whether this affects you. (Anymail's
|
||||
`"merge_field_format"` is unchanged, so if that's the only
|
||||
thing you have in esp_extra, no changes are needed.)
|
||||
|
||||
The new API format is considerably simpler and more logical.
|
||||
See :ref:`sendgrid-esp-extra` below for examples of the
|
||||
new format and a link to relevant SendGrid docs.
|
||||
|
||||
Anymail will raise an error if it detects an attempt to use
|
||||
the v2-only `"x-smtpapi"` settings in esp_extra when sending.
|
||||
|
||||
3. If you send messages with multiple Reply-To addresses, SendGrid
|
||||
no longer supports this. (Multiple reply emails in a single
|
||||
message are not common.)
|
||||
|
||||
Anymail will raise an error if you attempt to send a message with
|
||||
multiple Reply-To emails. (You can suppress the error with
|
||||
:setting:`ANYMAIL_IGNORE_UNSUPPORTED_FEATURES`, which will
|
||||
ignore all but the first reply address.)
|
||||
|
||||
|
||||
As an alternative, Anymail (for the time being) still includes
|
||||
a copy of the SendGrid v2 backend. See :ref:`sendgrid-v2-backend`
|
||||
below if you'd prefer to stay on the older SendGrid API.
|
||||
|
||||
|
||||
.. _sendgrid-v2-backend:
|
||||
|
||||
Legacy v2 API support
|
||||
---------------------
|
||||
|
||||
.. versionchanged:: 0.8
|
||||
|
||||
Anymail v0.8 switched to SendGrid's v3 Web API in its primary SendGrid
|
||||
email backend. SendGrid `encourages`_ all users to migrate to their v3 API.
|
||||
|
||||
For Anymail users who still need it, a legacy backend that calls SendGrid's
|
||||
earlier `Web API v2 Mail Send`_ remains available. Be aware that v2 support
|
||||
is considered deprecated and may be removed in a future Anymail release.
|
||||
|
||||
.. _encourages:
|
||||
https://sendgrid.com/docs/Classroom/Send/v3_Mail_Send/how_to_migrate_from_v2_to_v3_mail_send.html
|
||||
.. _Web API v2 Mail Send:
|
||||
https://sendgrid.com/docs/API_Reference/Web_API/mail.html
|
||||
|
||||
|
||||
To use Anymail's SendGrid v2 backend, edit your settings.py:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
EMAIL_BACKEND = "anymail.backends.sendgrid_v2.EmailBackend"
|
||||
ANYMAIL = {
|
||||
"SENDGRID_API_KEY": "<your API key>",
|
||||
}
|
||||
|
||||
The same :setting:`SENDGRID_API_KEY <ANYMAIL_SENDGRID_API_KEY>` will work
|
||||
with either Anymail's v2 or v3 SendGrid backend.
|
||||
|
||||
Nearly all of the documentation above for Anymail's v3 SendGrid backend
|
||||
also applies to the v2 backend, with the following changes:
|
||||
|
||||
.. setting:: ANYMAIL_SENDGRID_USERNAME
|
||||
.. setting:: ANYMAIL_SENDGRID_PASSWORD
|
||||
|
||||
.. rubric:: Username/password auth (SendGrid v2 only)
|
||||
|
||||
SendGrid v2 allows a username/password instead of an API key
|
||||
(though SendGrid encourages API keys for all new installations).
|
||||
If you must use username/password auth, set:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
EMAIL_BACKEND = "anymail.backends.sendgrid_v2.EmailBackend"
|
||||
ANYMAIL = {
|
||||
"SENDGRID_USERNAME": "<sendgrid credential with Mail permission>",
|
||||
"SENDGRID_PASSWORD": "<password for that credential>",
|
||||
# And leave out "SENDGRID_API_KEY"
|
||||
}
|
||||
|
||||
This is **not** the username/password that you use to log into SendGrid's
|
||||
dashboard. Create credentials specifically for sending mail in the
|
||||
`SendGrid credentials settings`_.
|
||||
|
||||
Either username/password or :setting:`SENDGRID_API_KEY <ANYMAIL_SENDGRID_API_KEY>`
|
||||
are required (but not both).
|
||||
|
||||
Anymail will also look for ``SENDGRID_USERNAME`` and ``SENDGRID_PASSWORD`` at the
|
||||
root of the settings file if neither ``ANYMAIL["SENDGRID_USERNAME"]``
|
||||
nor ``ANYMAIL_SENDGRID_USERNAME`` is set.
|
||||
|
||||
.. _SendGrid credentials settings: https://app.sendgrid.com/settings/credentials
|
||||
|
||||
|
||||
.. rubric:: Duplicate attachment filenames (SendGrid v2 limitation)
|
||||
|
||||
Anymail is not capable of communicating multiple attachments with
|
||||
the same filename to the SendGrid v2 API. (This also applies to multiple
|
||||
attachments with *no* filename, though not to inline images.)
|
||||
|
||||
If you are sending multiple attachments on a single message,
|
||||
make sure each one has a unique, non-empty filename.
|
||||
|
||||
|
||||
.. rubric:: Message bodies with ESP templates (SendGrid v2 quirk)
|
||||
|
||||
Anymail's SendGrid v2 backend will convert empty text and HTML bodies to single spaces whenever
|
||||
:attr:`~anymail.message.AnymailMessage.template_id` is set, to ensure the
|
||||
plaintext and HTML from your template are present in your outgoing email.
|
||||
This works around a `limitation in SendGrid's template rendering`_.
|
||||
|
||||
.. _limitation in SendGrid's template rendering:
|
||||
https://sendgrid.com/docs/API_Reference/Web_API_v3/Transactional_Templates/smtpapi.html#-Text-or-HTML-Templates
|
||||
|
||||
|
||||
.. rubric:: Multiple Reply-To addresses (SendGrid v2 only)
|
||||
|
||||
Unlike SendGrid's v3 API, Anymail is able to support multiple
|
||||
Reply-To addresses with their v2 API.
|
||||
|
||||
|
||||
.. rubric:: esp_extra with SendGrid v2
|
||||
|
||||
Anymail's :attr:`~anymail.message.AnymailMessage.esp_extra` attribute
|
||||
is merged directly with the API parameters, so the format varies
|
||||
between SendGrid's v2 and v3 APIs. With the v2 API, most interesting
|
||||
settings appear beneath `'x-smtpapi'`. Example:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
message.esp_extra = {
|
||||
'x-smtpapi': { # for SendGrid v2 API
|
||||
"asm_group": 1, # Assign SendGrid unsubscribe group for this message
|
||||
"asm_groups_to_display": [1, 2, 3],
|
||||
"filters": {
|
||||
"subscriptiontrack": { # Insert SendGrid subscription management links
|
||||
"settings": {
|
||||
"text/html": "If you would like to unsubscribe <% click here %>.",
|
||||
"text/plain": "If you would like to unsubscribe click here: <% %>.",
|
||||
"enable": 1
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
The value of :attr:`esp_extra` should be a `dict` of parameters for SendGrid's
|
||||
`v2 mail.send API`_. Any keys in the dict will override Anymail's normal values
|
||||
for that parameter, except that `'x-smtpapi'` will be merged.
|
||||
|
||||
.. _v2 mail.send API:
|
||||
https://sendgrid.com/docs/API_Reference/Web_API/mail.html#-send
|
||||
|
||||
Reference in New Issue
Block a user