mirror of
https://github.com/pacnpal/django-anymail.git
synced 2025-12-20 11:51:05 -05:00
150 lines
4.6 KiB
ReStructuredText
150 lines
4.6 KiB
ReStructuredText
.. _postmark-backend:
|
|
|
|
Postmark
|
|
========
|
|
|
|
Anymail integrates with the `Postmark`_ transactional email service,
|
|
using their `HTTP email API`_.
|
|
|
|
.. _Postmark: https://postmarkapp.com/
|
|
.. _HTTP email API: http://developer.postmarkapp.com/developer-api-email.html
|
|
|
|
|
|
Settings
|
|
--------
|
|
|
|
.. rubric:: EMAIL_BACKEND
|
|
|
|
To use Anymail's Postmark backend, set:
|
|
|
|
.. code-block:: python
|
|
|
|
EMAIL_BACKEND = "anymail.backends.postmark.PostmarkBackend"
|
|
|
|
in your settings.py. (Watch your capitalization: Postmark spells their name with a
|
|
lowercase "m", so Anymail does too.)
|
|
|
|
|
|
.. setting:: ANYMAIL_POSTMARK_SERVER_TOKEN
|
|
|
|
.. rubric:: POSTMARK_SERVER_TOKEN
|
|
|
|
Required. A Postmark server token.
|
|
|
|
.. code-block:: python
|
|
|
|
ANYMAIL = {
|
|
...
|
|
"POSTMARK_SERVER_TOKEN": "<your server token>",
|
|
}
|
|
|
|
Anymail will also look for ``POSTMARK_SERVER_TOKEN`` at the
|
|
root of the settings file if neither ``ANYMAIL["POSTMARK_SERVER_TOKEN"]``
|
|
nor ``ANYMAIL_POSTMARK_SERVER_TOKEN`` is set.
|
|
|
|
You can override the server token for an individual message in
|
|
its :ref:`esp_extra <postmark-esp-extra>`.
|
|
|
|
|
|
.. setting:: ANYMAIL_POSTMARK_API_URL
|
|
|
|
.. rubric:: POSTMARK_API_URL
|
|
|
|
The base url for calling the Postmark API.
|
|
|
|
The default is ``POSTMARK_API_URL = "https://api.postmarkapp.com/"``
|
|
(It's unlikely you would need to change this.)
|
|
|
|
|
|
.. _postmark-esp-extra:
|
|
|
|
esp_extra support
|
|
-----------------
|
|
|
|
To use Postmark features not directly supported by Anymail, you can
|
|
set a message's :attr:`~anymail.message.AnymailMessage.esp_extra` to
|
|
a `dict` that will be merged into the json sent to Postmark's
|
|
`email API`_.
|
|
|
|
Example:
|
|
|
|
.. code-block:: python
|
|
|
|
message.esp_extra = {
|
|
'HypotheticalFuturePostmarkParam': '2022', # merged into send params
|
|
'server_token': '<API server token for just this message>',
|
|
}
|
|
|
|
|
|
(You can also set `"esp_extra"` in Anymail's
|
|
:ref:`global send defaults <send-defaults>` to apply it to all
|
|
messages.)
|
|
|
|
|
|
.. _email API: http://developer.postmarkapp.com/developer-api-email.html
|
|
|
|
|
|
Limitations and quirks
|
|
----------------------
|
|
|
|
Postmark has excellent support for standard email functionality, but does
|
|
not support all the tracking and reporting additions offered by some other
|
|
ESPs.
|
|
|
|
Anymail normally raises an :exc:`~anymail.exceptions.AnymailUnsupportedFeature`
|
|
error when you try to send a message using features that Postmark doesn't support
|
|
You can tell Anymail to suppress these errors and send the messages anyway --
|
|
see :ref:`unsupported-features`.
|
|
|
|
**Single tag**
|
|
Postmark allows a maximum of one tag per message. If your message has two or more
|
|
:attr:`~anymail.message.AnymailMessage.tags`, you'll get an
|
|
:exc:`~anymail.exceptions.AnymailUnsupportedFeature` error---or
|
|
if you've enabled :setting:`ANYMAIL_IGNORE_UNSUPPORTED_FEATURES`,
|
|
Anymail will use only the first tag.
|
|
|
|
**No metadata**
|
|
Postmark does not support attaching :attr:`~anymail.message.AnymailMessage.metadata`
|
|
to messages.
|
|
|
|
**No click-tracking**
|
|
Postmark supports :attr:`~anymail.message.AnymailMessage.track_open`,
|
|
but not :attr:`~anymail.message.AnymailMessage.track_clicks`.
|
|
|
|
**No delayed sending**
|
|
Postmark does not support :attr:`~anymail.message.AnymailMessage.send_at`.
|
|
|
|
|
|
|
|
.. _postmark-webhooks:
|
|
|
|
Status tracking webhooks
|
|
------------------------
|
|
|
|
If you are using Anymail's normalized :ref:`status tracking <event-tracking>`, enter
|
|
the url in your `Postmark account settings`_, under Servers > *your server name* >
|
|
Settings > Outbound > Webhooks. You should enter this same Anymail tracking URL
|
|
for both the "Bounce webhook" and "Opens webhook" (if you want to receive both
|
|
types of events):
|
|
|
|
:samp:`https://{random}:{random}@{yoursite.example.com}/anymail/postmark/tracking/`
|
|
|
|
* *random:random* is an :setting:`ANYMAIL_WEBHOOK_AUTHORIZATION` shared secret
|
|
* *yoursite.example.com* is your Django site
|
|
|
|
Anymail doesn't care about the "include bounce content" and "post only on first open"
|
|
Postmark webhook settings: whether to use them is your choice.
|
|
|
|
If you use multiple Postmark servers, you'll need to repeat entering the webhook
|
|
settings for each of them.
|
|
|
|
Postmark will report these Anymail :attr:`~anymail.signals.AnymailTrackingEvent.event_type`\s:
|
|
rejected, failed, bounced, deferred, autoresponded, opened, complained, unsubscribed, subscribed.
|
|
(Postmark does not support sent, delivered, or clicked events.)
|
|
|
|
The event's :attr:`~anymail.signals.AnymailTrackingEvent.esp_event` field will be
|
|
a `dict` of Postmark `bounce <http://developer.postmarkapp.com/developer-bounce-webhook.html>`_
|
|
or `open <http://developer.postmarkapp.com/developer-open-webhook.html>`_ webhook data.
|
|
|
|
.. _Postmark account settings: https://account.postmarkapp.com/servers
|