Postmark¶
Anymail integrates with the Postmark transactional email service, using their HTTP email API.
Settings¶
EMAIL_BACKEND
To use Anymail’s Postmark backend, set:
EMAIL_BACKEND = "anymail.backends.postmark.EmailBackend"
in your settings.py.
POSTMARK_SERVER_TOKEN
Required. A Postmark server token.
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 esp_extra.
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.)
esp_extra support¶
To use Postmark features not directly supported by Anymail, you can
set a message’s esp_extra
to
a dict
that will be merged into the json sent to Postmark’s
email API.
Example:
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
global send defaults to apply it to all
messages.)
Limitations and quirks¶
Postmark does not support a few tracking and reporting additions offered by other ESPs.
Anymail normally raises an 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 Unsupported features.
- Single tag
- Postmark allows a maximum of one tag per message. If your message has two or more
tags
, you’ll get anAnymailUnsupportedFeature
error—or if you’ve enabledANYMAIL_IGNORE_UNSUPPORTED_FEATURES
, Anymail will use only the first tag. - No metadata
- Postmark does not support attaching
metadata
to messages. - No delayed sending
- Postmark does not support
send_at
. - Click-tracking
Postmark supports several link-tracking options. Anymail treats
track_clicks
as Postmark’s “HtmlAndText” option when True.If you would prefer Postmark’s “HtmlOnly” or “TextOnly” link-tracking, you could either set that as a Postmark server-level default (and use
message.track_clicks = False
to disable tracking for specific messages), or use something likemessage.esp_extra = {'TrackLinks': "HtmlOnly"}
to specify a particular option.
Batch sending/merge and ESP templates¶
Postmark supports ESP stored templates
populated with global merge data for all recipients, but does not
offer batch sending with per-recipient merge data.
Anymail’s merge_data
message attribute is not supported with the Postmark backend.
To use a Postmark template, set the message’s
template_id
to the numeric
Postmark “TemplateID” and supply the “TemplateModel” using
the merge_global_data
message attribute:
message = EmailMessage( ... subject=None, # use template subject to=["[email protected]"] # single recipient... # ...multiple to emails would all get the same message # (and would all see each other's emails in the "to" header) ) message.template_id = 80801 # use this Postmark template message.merge_global_data = { 'name': "Alice", 'order_no': "12345", 'ship_date': "May 15", 'items': [ {'product': "Widget", 'price': "9.99"}, {'product': "Gadget", 'price': "17.99"}, ], }
Set the EmailMessage’s subject to None
to use the subject from
your Postmark template, or supply a subject with the message to override
the template value.
See this Postmark blog post on templates for more information.
Status tracking webhooks¶
If you are using Anymail’s normalized status 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 all of the “Delivery webhook,” “Bounce webhook,” and “Opens webhook” (if you want to receive all these types of events):
https://random:random@yoursite.example.com/anymail/postmark/tracking/
- random:random is an
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 event_type
s:
rejected, failed, bounced, deferred, delivered, autoresponded, opened, clicked, complained,
unsubscribed, subscribed. (Postmark does not support sent–what it calls “processed”–events
through webhooks.)
The event’s esp_event
field will be
a dict
of Postmark delivery,
bounce,
or open webhook data.