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 an AnymailUnsupportedFeature error—or if you’ve enabled ANYMAIL_IGNORE_UNSUPPORTED_FEATURES, Anymail will use only the first tag.
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 like message.esp_extra = {'TrackLinks': "HtmlOnly"} to specify a particular option.

No envelope sender overrides
Postmark does not support overriding envelope_sender on individual messages. (You can configure custom return paths for each sending domain in the Postmark control panel.)

Batch sending/merge and ESP templates

Postmark offers both ESP stored templates and batch sending with per-recipient merge data.

Changed in version 4.2: Added Postmark merge_data and batch sending support. (Earlier Anymail releases only supported merge_global_data with Postmark.)

To use a Postmark template, set the message’s template_id to either the numeric Postmark “TemplateID” or its string “TemplateAlias” (which is not the template’s name). You can find a template’s numeric id near the top right in Postmark’s template editor, and set the alias near the top right above the name.

Changed in version 5.0: Earlier Anymail releases only allowed numeric template IDs.

Supply the Postmark “TemplateModel” variables using Anymail’s normalized merge_data and merge_global_data message attributes:

message = EmailMessage(
    # (subject and body come from the template, so don't include those)
    to=["[email protected]", "Bob <[email protected]>"]
)
message.template_id = 80801  # Postmark template id or alias
message.merge_data = {
    '[email protected]': {'name': "Alice", 'order_no': "12345"},
    '[email protected]': {'name': "Bob", 'order_no': "54321"},
}
message.merge_global_data = {
    'ship_date': "May 15",
}

Postmark does not allow overriding the message’s subject or body with a template. (You can customize the subject by including variables in the template’s subject.)

When you supply per-recipient merge_data, Anymail automatically switches to Postmark’s batch send API, so that each “to” recipient sees only their own email address. (Any cc’s or bcc’s will be duplicated for every to-recipient.)

If you want to use batch sending with a regular message (without a template), set merge data to an empty dict: message.merge_data = {}.

See this Postmark blog post on templates for more information.

Status tracking webhooks

If you are using Anymail’s normalized status tracking, set up a webhook in your Postmark account settings, under Servers > your server name > Settings > Webhooks. The webhook URL is:

https://random:random@yoursite.example.com/anymail/postmark/tracking/

Choose all the event types you want to receive. Anymail doesn’t care about the “include messsage content” and “post only on first open” options; 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_types: 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, spam-complaint, open-tracking, or click data.

Inbound webhook

If you want to receive email from Postmark through Anymail’s normalized inbound handling, follow Postmark’s Inbound Processing guide to configure an inbound server pointing to Anymail’s inbound webhook.

The InboundHookUrl setting will be:

https://random:random@yoursite.example.com/anymail/postmark/inbound/

Anymail handles the “parse an email” part of Postmark’s instructions for you, but you’ll likely want to work through the other sections to set up a custom inbound domain, and perhaps configure inbound spam blocking.