Postmarker

Python client for the Postmark email API.

Postmarker covers Postmark's API beyond sending: templates, bounces, suppressions, message streams, stats, servers and domains. It also ships a Django email backend, Postmark webhook wrappers and a pytest fixture for your tests.

Installation

uv pip install postmarker

To inline <style> CSS into HTML emails, install the css-inline extra and create the client with inline_css=True:

uv pip install 'postmarker[css-inline]'

Usage

from postmarker.core import PostmarkClient

postmark = PostmarkClient(server_token="POSTMARK_API_TEST")
postmark.emails.send(
    From="sender@example.com",
    To="receiver@example.com",
    Subject="Postmark test",
    HtmlBody="<strong>Hello</strong> dear Postmark user.",
)
# {"ErrorCode": 0, "Message": "Test job accepted", "MessageID": "...", ...}

With the POSTMARK_API_TEST token, Postmark validates the request without delivering it. To send real emails, use the server token from your server's API Tokens tab in Postmark. From must be a confirmed sender signature or an address on a verified domain.

Send with a template:

postmark.emails.send_with_template(
    TemplateAlias="welcome",
    TemplateModel={"name": "Jane"},
    From="sender@example.com",
    To="receiver@example.com",
)

Send a batch. Postmarker splits it into requests of 500 messages, Postmark's limit:

messages = [
    {"From": "sender@example.com", "To": to, "Subject": "Hi", "TextBody": "Hello"}
    for to in ("first@example.com", "second@example.com")
]
responses = postmark.emails.send_batch(*messages)
# Postmark accepts or rejects each message separately
failed = [response for response in responses if response["ErrorCode"] != 0]

Add headers and attachments:

email = postmark.emails.Email(
    From="sender@example.com",
    To="receiver@example.com",
    Subject="Report",
    TextBody="See the attached report.",
)
email["X-Accept-Language"] = "en-us, en"
email.attach("/home/user/report.pdf")
email.attach_binary(content=b"content", filename="readme.txt")
email.send()

A rejected request raises ClientError with Postmark's error code:

from postmarker.exceptions import ClientError

try:
    postmark.emails.send(
        From="sender@example.com",
        To="receiver@example.com",
        TextBody="Hello",
    )
except ClientError as exc:
    print(exc.error_code)  # For example, 406 for an inactive recipient

Async

AsyncPostmarkClient has the same API, with every method that makes a request as a coroutine. Install the async extra:

uv pip install 'postmarker[async]'

from postmarker.core import AsyncPostmarkClient

async with AsyncPostmarkClient(server_token="POSTMARK_API_TEST") as postmark:
    await postmark.emails.send(
        From="sender@example.com",
        To="receiver@example.com",
        TextBody="Hello",
    )

See the async guide for properties, fixtures and differences.

Django

Django 6.1+:

MAILERS = {
    "default": {
        "BACKEND": "postmarker.django.EmailBackend",
        "OPTIONS": {"token": "<YOUR POSTMARK SERVER TOKEN>"},
    },
}

Django 5.2 and 6.0:

EMAIL_BACKEND = "postmarker.django.EmailBackend"
POSTMARK = {"TOKEN": "<YOUR POSTMARK SERVER TOKEN>"}

Django then sends send_mail, EmailMessage and emails from third-party apps through Postmark. The Django guide covers tags, metadata, message streams and signals.

Testing

Postmarker ships a postmark_request pytest fixture. It mocks requests to Postmark and records what your code sent, through PostmarkClient or the Django backend:

def test_welcome_email(postmark_request):
    send_welcome_email("jane@example.com")  # Your code that sends an email
    assert postmark_request.call_args.kwargs["json"]["To"] == "jane@example.com"

Features

• Server APIs: Emails, Templates with layouts, Bounces, Messages (inbound, outbound, opens and clicks), Message Streams, Suppressions, Server, Stats and Triggers.
• Account APIs: Domains, Sender signatures, Servers and pushing templates between servers.
• Status and Spam check APIs.
• Webhook wrappers: Inbound, Delivery, Open, Click, Bounce, Spam complaint and Subscription change.
• Sending email.message.Message instances.
• CSS inlining via css-inline.
• Async client (AsyncPostmarkClient) via the async extra.
• Django email backend and Tornado helper.
• Type annotations, with a py.typed marker.

Documentation

https://postmarker.readthedocs.io/en/stable/

Python support

Postmarker supports CPython 3.11 to 3.15 and PyPy 3.11. The Django email backend supports Django 5.2, 6.0 and 6.1.