Skip to content

API Reference

PostmarkClient exposes each Postmark API as a manager, e.g. postmark.templates. Managers return models. Each Postmark field of a model is an attribute with the same name, e.g. template.Name.

Client

PostmarkClient 

PostmarkClient(
    server_token=None,
    account_token=None,
    verbosity=0,
    max_retries=0,
    timeout=None,
    logs_stream=sys.stdout,
    root_api_url=DEFAULT_API,
    inline_css=False,
)

Bases: BaseClient

Basic class for API clients. Provides basic functionality to make requests.

from_config classmethod 

from_config(config, prefix='postmark_', is_uppercase=False)

Helper method for instantiating PostmarkClient from dict-like objects.

spamcheck 

spamcheck(dump, options='long')

AsyncPostmarkClient takes the same arguments; see Async client. Every manager and model that makes requests has an Async twin in the same module, e.g. AsyncBounceManager, with the same members as coroutines.

AsyncPostmarkClient 

AsyncPostmarkClient(
    server_token=None,
    account_token=None,
    verbosity=0,
    max_retries=0,
    timeout=None,
    logs_stream=sys.stdout,
    root_api_url=DEFAULT_API,
    inline_css=False,
)

Bases: BaseClient

Async twin of :py:class:PostmarkClient: every method that makes a request is a coroutine.

aclose async 

aclose()

Emails

postmark.emails, see Emails.

EmailManager

Bases: BaseEmailManager[Email, EmailTemplate, EmailBatch, EmailTemplateBatch], ModelManager[Model]

Sends emails via Postmark REST API.

send 

send(
    message=None,
    From=None,
    To=None,
    Cc=None,
    Bcc=None,
    Subject=None,
    Tag=None,
    HtmlBody=None,
    TextBody=None,
    Metadata=None,
    ReplyTo=None,
    Headers=None,
    TrackOpens=None,
    TrackLinks="None",
    Attachments=None,
    MessageStream=None,
)

Sends a single email.

Parameters:

Name Type Description Default
message Email | Message | None

:py:class:Email or email.message.Message instance.

 None
From str

The sender email address.

 None
To Recipients | None

Recipient's email address. Multiple recipients could be specified as a list or string with comma separated values.

 None
Cc Recipients | None

Cc recipient's email address. Multiple Cc recipients could be specified as a list or string with comma separated values.

 None
Bcc Recipients | None

Bcc recipient's email address. Multiple Bcc recipients could be specified as a list or string with comma separated values.

 None
Subject str

Email subject.

 None
Tag str

Email tag.

 None
HtmlBody str

HTML email message.

 None
TextBody str

Plain text email message.

 None
ReplyTo str

Reply To override email address.

 None
Headers dict

Dictionary of custom headers to include.

 None
TrackOpens bool

Activate open tracking for this email.

 None
TrackLinks str

Activate link tracking for links in the HTML or Text bodies of this email.

 'None'
Attachments list

List of attachments.

 None

Returns:

Type Description
`dict`

Information about sent email.

send_with_template 

send_with_template(
    *,
    TemplateId=None,
    TemplateModel,
    From,
    To,
    TemplateAlias=None,
    Cc=None,
    Bcc=None,
    Subject=None,
    Tag=None,
    ReplyTo=None,
    Headers=None,
    TrackOpens=None,
    TrackLinks="None",
    Attachments=None,
    InlineCss=True,
    Metadata=None,
    MessageStream=None,
)

send_batch 

send_batch(*emails, **extra)

Sends an email batch.

Parameters:

Name Type Description Default
emails Email | Message | dict[str, Any]

:py:class:Email instances, :py:class:email.message.Message instances or dictionaries, passed as separate arguments.

 ()
extra Any

dictionary with extra arguments for every message in the batch.

 {}

send_template_batch 

send_template_batch(*emails, **extra)

Sends an email batch.

Parameters:

Name Type Description Default
emails EmailTemplate | dict[str, Any]

:py:class:EmailTemplate instances or dictionaries, passed as separate arguments.

 ()
extra Any

dictionary with extra arguments for every message in the batch.

 {}

Email 

Email(
    From,
    To,
    Cc=None,
    Bcc=None,
    Subject=None,
    Tag=None,
    HtmlBody=None,
    TextBody=None,
    Metadata=None,
    ReplyTo=None,
    Headers=None,
    TrackOpens=None,
    TrackLinks="None",
    Attachments=None,
    MessageStream=None,
)

Constructs :py:class:Email instance.

Returns:

Type Description
EmailT

:py:class:Email

EmailTemplate 

EmailTemplate(
    *,
    TemplateId=None,
    TemplateModel,
    From,
    To,
    TemplateAlias=None,
    Cc=None,
    Bcc=None,
    Subject=None,
    Tag=None,
    ReplyTo=None,
    Headers=None,
    TrackOpens=None,
    TrackLinks="None",
    Attachments=None,
    InlineCss=True,
    Metadata=None,
    MessageStream=None,
)

Constructs :py:class:EmailTemplate instance.

Returns:

Type Description
TemplateT

:py:class:EmailTemplate

EmailBatch 

EmailBatch(*emails)

Constructs :py:class:EmailBatch instance.

Returns:

Type Description
BatchT

:py:class:EmailBatch

EmailTemplateBatch 

EmailTemplateBatch(*emails)

Constructs :py:class:EmailTemplateBatch instance.

Returns:

Type Description
TemplateBatchT

:py:class:EmailTemplateBatch

Email

Bases: BaseEmailMessage

attach 

attach(*payloads)

Appends given payloads to the current payload.

Parameters:

Name Type Description Default
payloads AttachmentData
()

Returns:

Type Description
None

None.

attach_binary 

attach_binary(content, filename)

Attaches given binary data.

Parameters:

Name Type Description Default
content bytes

Binary data to be attached.

 required
filename str
required

Returns:

Type Description
None

None.

send 

send()

EmailTemplate

Bases: BaseEmailTemplate

attach 

attach(*payloads)

Appends given payloads to the current payload.

Parameters:

Name Type Description Default
payloads AttachmentData
()

Returns:

Type Description
None

None.

attach_binary 

attach_binary(content, filename)

Attaches given binary data.

Parameters:

Name Type Description Default
content bytes

Binary data to be attached.

 required
filename str
required

Returns:

Type Description
None

None.

send 

send()

Templates

postmark.templates, see Templates. push needs the account token.

TemplateManager

Bases: ModelManager[Template]

all 

all(Count=100, Offset=0, TemplateType=None, LayoutTemplate=None)

Returns templates, optionally filtered by TemplateType (All, Standard, Layout) or layout alias.

get 

get(id)

create 

create(
    Name,
    Subject=None,
    HtmlBody=None,
    TextBody=None,
    Alias=None,
    TemplateType=None,
    LayoutTemplate=None,
)

Creates a template.

Parameters:

Name Type Description Default
Name str

Name of template.

 required
Subject str | None

Subject content. Required for standard templates, rejected for layouts.

 None
HtmlBody str | None

HTML body content.

 None
TextBody str | None

Text body content.

 None
Alias str | None

Template alias.

 None
TemplateType str | None

Standard (default) or Layout.

 None
LayoutTemplate str | None

Alias of the layout for a standard template.

 None

edit 

edit(
    id,
    Name=None,
    Subject=None,
    HtmlBody=None,
    TextBody=None,
    Alias=None,
    LayoutTemplate=None,
)

Edits a template. Unset fields stay unchanged; LayoutTemplate="" removes the layout.

delete 

delete(id)

validate 

validate(
    Subject=None,
    HtmlBody=None,
    TextBody=None,
    TestRenderModel=None,
    InlineCssForHtmlTestRender=True,
    TemplateType=None,
    LayoutTemplate=None,
)

Validates template content; LayoutTemplate renders a standard template inside that layout.

push 

push(SourceServerID, DestinationServerID, PerformChanges)

Copies changed templates to another server. Needs the account token.

Parameters:

Name Type Description Default
PerformChanges bool

False for a dry run that only lists the changes.

 required

Template

Bases: BaseTemplate

get 

get()

edit 

edit(**kwargs)

delete 

delete()

Bounces

postmark.bounces, see Bounces.

BounceManager

Bases: BaseBounceManager[Bounce], ModelManager[Bounce]

Encapsulates logic about bounces.

deliverystats property 

deliverystats

Returns number of inactive emails and list of bounce types with total counts.

tags property 

tags

A list of tags that have generated bounces for a given server.

Bounce 

Bounce(json)

Constructs new Bounce instance from JSON-encoded string. Intended to use for bounce webhook processing.

Parameters:

Name Type Description Default
json str | bytes

str

 required

Returns:

Type Description
ModelT

:py:class:Bounce

SpamComplaint 

SpamComplaint(json)

Constructs a :py:class:SpamComplaint from the spam complaint webhook payload.

Parameters:

Name Type Description Default
json str | bytes

str

 required

activate 

activate(id)

Activates a bounce.

Parameters:

Name Type Description Default
id int

Bounce ID.

 required

Returns:

Type Description
`dict`

Activation result and bounce data.

all 

all(
    count=500,
    offset=0,
    type=None,
    inactive=None,
    emailFilter=None,
    tag=None,
    messageID=None,
    fromdate=None,
    todate=None,
)

Returns many bounces.

Parameters:

Name Type Description Default
count int

Number of bounces to return per request.

 500
offset int

Number of bounces to skip.

 0
type str

Filter by type of bounce.

 None
inactive bool

Filter by emails that were deactivated by Postmark due to the bounce.

 None
emailFilter str

Filter by email address.

 None
tag str

Filter by tag.

 None
messageID str

Filter by messageID.

 None
fromdate date

Filter messages starting from the date specified (inclusive).

 None
todate date

Filter messages up to the date specified (inclusive).

 None

Returns:

Type Description
`list`

A list of :py:class:Bounce instances.

get 

get(id)

Returns a single bounce.

Parameters:

Name Type Description Default
id int

Bounce ID.

 required

get_dump 

get_dump(id)

Gets an SMTP data dump.

Parameters:

Name Type Description Default
id int

Bounce ID.

 required

Returns:

Type Description
`str` | `None`

A dump of SMTP data if it is available.

Bounce

Bases: MessageModel

Bounce model.

dump property 

dump

Gets SMTP data dump.

Returns:

Type Description
`str` | `None`

Dump of SMTP data if it is available.

message property 

message

activate 

activate()

Activates the bounce instance and updates it with the latest data.

Returns:

Type Description
`str`

Activation status.

SpamComplaint

Bases: BaseSpamComplaint, Bounce

Spam complaint webhook model. Postmark records spam complaints as bounces that can't be activated.

dump property 

dump

Gets SMTP data dump.

Returns:

Type Description
`str` | `None`

Dump of SMTP data if it is available.

message property 

message

Messages

postmark.messages.outbound, postmark.messages.outbound.opens, postmark.messages.outbound.clicks and postmark.messages.inbound, see Messages.

OutboundMessageManager

Bases: SubModelManager[OutboundMessage]

all 

all(
    count=500,
    offset=0,
    recipient=None,
    fromemail=None,
    tag=None,
    status=None,
    todate=None,
    fromdate=None,
    subject=None,
)

All outbound messages.

Lets you get all the details about any outbound or inbound message that you sent or received through a specific server. Messages expire after 45 days.

Parameters:

Name Type Description Default
count int

Number of messages to return per request.

 500
offset int

Number of messages to skip.

 0
recipient str

Filter by the user who was receiving the email.

 None
fromemail str

Filter by the sender email address.

 None
tag str

Filter by tag.

 None
status str

Filter by status (queued or sent).

 None
todate date

Filter messages up to the date specified (inclusive).

 None
fromdate date

Filter messages starting from the date specified (inclusive).

 None
subject str | None

Filter by email subject.

 None

Returns:

Type Description
`list`

A list of :py:class:OutboundMessage instances.

get 

get(id)

get_dump 

get_dump(id)

OutboundMessage

Bases: BaseOutboundMessage, BaseMessage

get 

get()

get_dump 

get_dump()

opens 

opens(count=500, offset=0)

clicks 

clicks(count=500, offset=0)

Clicks on tracked links in this message, as ClicksManager.get returns them.

OpensManager

Bases: BaseOpensManager[Open], ModelManager[Open]

all 

all(
    count=500,
    offset=0,
    recipient=None,
    tag=None,
    client_name=None,
    client_company=None,
    client_family=None,
    os_name=None,
    os_family=None,
    os_company=None,
    platform=None,
    country=None,
    region=None,
    city=None,
)

get 

get(id, count=500, offset=0)

Open 

Open(json)

ClicksManager

Bases: BaseClicksManager[Click], ModelManager[Click]

all 

all(
    count=500,
    offset=0,
    recipient=None,
    tag=None,
    client_name=None,
    client_company=None,
    client_family=None,
    os_name=None,
    os_family=None,
    os_company=None,
    platform=None,
    country=None,
    region=None,
    city=None,
    messagestream=None,
)

Clicks on tracked links in outbound messages, one per recipient and link.

Parameters:

Name Type Description Default
count int | None

Number of clicks to return; None for all.

 500
offset int

Number of clicks to skip.

 0
messagestream str | None

Message stream ID; Postmark defaults to the outbound transactional stream.

 None

get 

get(id, count=500, offset=0)

Clicks on tracked links in one message, as the raw TotalCount and Clicks response.

Click 

Click(json)

Wraps a link click webhook payload.

InboundMessageManager

Bases: BaseInboundMessageManager[InboundMessage], ModelManager[InboundMessage]

all 

all(
    count=500,
    offset=0,
    recipient=None,
    fromemail=None,
    tag=None,
    subject=None,
    mailboxhash=None,
    status=None,
    todate=None,
    fromdate=None,
)

All inbound messages.

Parameters:

Name Type Description Default
count int | None

Number of messages to return per request.

 500
offset int

Number of messages to skip.

 0
recipient str | None

Filter by the user who was receiving the email.

 None
fromemail str | None

Filter by the sender email address.

 None
tag str | None

Filter by tag.

 None
subject str | None

Filter by email subject.

 None
mailboxhash str | None

Filter by mailboxhash.

 None
status str | None

Filter by status (blocked, processed, queued, failed, scheduled).

 None
todate date

Filter messages up to the date specified (inclusive).

 None
fromdate date

Filter messages starting from the date specified (inclusive).

 None

Returns:

Type Description
`list`

A list of :py:class:InboundMessage instances.

get 

get(id)

bypass 

bypass(id)

retry 

retry(id)

InboundMessage 

InboundMessage(json)

InboundMessage

Bases: BaseInboundMessage, BaseMessage

Attachments property 

Attachments

get 

get()

bypass 

bypass()

retry 

retry()

as_mime 

as_mime()

Attachment

Bases: Model

decoded property 

decoded

save 

save(directory)

as_mime 

as_mime()

Message Streams

postmark.message_streams, see Message Streams.

MessageStreamsManager

Bases: ModelManager[MessageStream]

all 

all(MessageStreamType=None, IncludeArchivedStreams=None)

Lists the server's message streams.

Parameters:

Name Type Description Default
MessageStreamType str | None

All (default), Inbound, Transactional or Broadcasts.

 None
IncludeArchivedStreams bool | None

Include archived streams; False by default.

 None

get 

get(id)

create 

create(
    ID,
    Name,
    MessageStreamType,
    Description=None,
    SubscriptionManagementConfiguration=None,
)

Creates a message stream.

Parameters:

Name Type Description Default
ID str

Stream ID to send messages with, e.g. transactional-dev.

 required
MessageStreamType str

Broadcasts or Transactional.

 required
SubscriptionManagementConfiguration dict[str, Any] | None

E.g. {"UnsubscribeHandlingType": "Postmark"}.

 None

edit 

edit(id, Name=None, Description=None, SubscriptionManagementConfiguration=None)

Updates the given fields of a message stream; omitted fields stay unchanged.

archive 

archive(id)

Archives a message stream. Postmark deletes it after ExpectedPurgeDate from the response.

unarchive 

unarchive(id)

Restores an archived message stream before its ExpectedPurgeDate.

MessageStream

Bases: Model

get 

get()

edit 

edit(**kwargs)

archive 

archive()

unarchive 

unarchive()

Sender signatures

postmark.senders, see Sender signatures. Needs the account token.

SenderSignaturesManager

Bases: ModelManager[SenderSignature]

all 

all(count=500, offset=0)

Gets a list of sender signatures containing brief details associated with your account.

get 

get(id)

Gets all the details for a specific sender signature.

create 

create(
    FromEmail,
    Name,
    ReplyToEmail=None,
    ReturnPathDomain=None,
    ConfirmationPersonalNote=None,
)

Creates a sender signature; ConfirmationPersonalNote goes to the confirmation email (max 400 chars).

edit 

edit(
    id,
    Name,
    ReplyToEmail=None,
    ReturnPathDomain=None,
    ConfirmationPersonalNote=None,
)

delete 

delete(id)

resend 

resend(id)

verifyspf 

verifyspf(id)

SenderSignature

Bases: Model

get 

get()

edit 

edit(**kwargs)

delete 

delete()

resend 

resend()

verifyspf 

verifyspf()

Server

postmark.server, see Server.

ServerManager

Bases: ModelManager[Server]

Lets you get or edit details of the specific server.

get 

get()

edit 

edit(**kwargs)

Server

Bases: BaseServer

edit 

edit(**kwargs)

Servers

postmark.servers, see Servers. Needs the account token.

ServersManager

Bases: ModelManager[AccountServer]

Lets you list, get, create, edit or delete servers of the account.

all 

all(count=500, offset=0, name=None)

Returns servers, filtered by a substring of their name if name is given.

get 

get(id)

create 

create(Name, **kwargs)

Creates a server; other fields from Postmark's Servers API go as keyword arguments.

edit 

edit(id, **kwargs)

delete 

delete(id)

AccountServer

Bases: BaseAccountServer

A server of the account, managed with the account token.

get 

get()

edit 

edit(**kwargs)

delete 

delete()

Status

postmark.status and postmark.status.incidents, see Status.

StatusManager

Bases: ModelManager[Model]

Gathers logic about Postmark systems status.

services property 

services

availability property 

availability

delivery property 

delivery

get 

get()

IncidentsManager

Bases: ModelManager[Incident]

last property 

last

all 

all()

get 

get(id)

Stats

postmark.stats, see Stats.

StatsManager

Bases: ModelManager[Model]

bounces 

bounces(tag=None, fromdate=None, todate=None)

Gets total counts of emails you’ve sent out that have been returned as bounced.

browserfamilies 

browserfamilies(tag=None, fromdate=None, todate=None)

Gets an overview of the browsers used to open links in your emails.

This is only recorded when Link Tracking is enabled for that email.

clicks 

clicks(tag=None, fromdate=None, todate=None)

Gets total counts of unique links that were clicked.

clicks_platforms 

clicks_platforms(tag=None, fromdate=None, todate=None)

Gets an overview of the browser platforms used to open your emails.

This is only recorded when Link Tracking is enabled for that email.

emailclients 

emailclients(tag=None, fromdate=None, todate=None)

Gets an overview of the email clients used to open your emails.

This is only recorded when open tracking is enabled for that email.

location 

location(tag=None, fromdate=None, todate=None)

Gets an overview of which part of the email links were clicked from (HTML or Text).

This is only recorded when Link Tracking is enabled for that email.

opens 

opens(tag=None, fromdate=None, todate=None)

Gets total counts of recipients who opened your emails.

This is only recorded when open tracking is enabled for that email.

opens_platforms 

opens_platforms(tag=None, fromdate=None, todate=None)

Gets an overview of the platforms used to open your emails.

This is only recorded when open tracking is enabled for that email.

overview 

overview(tag=None, fromdate=None, todate=None)

Gets a brief overview of statistics for all of your outbound email.

readtimes 

readtimes(tag=None, fromdate=None, todate=None)

Gets the length of time that recipients read emails along with counts for each time.

This is only recorded when open tracking is enabled for that email. Read time tracking stops at 20 seconds, so any read times above that will appear in the 20s+ field.

sends 

sends(tag=None, fromdate=None, todate=None)

Gets a total count of emails you’ve sent out.

spam 

spam(tag=None, fromdate=None, todate=None)

Gets a total count of recipients who have marked your email as spam.

tracked 

tracked(tag=None, fromdate=None, todate=None)

Gets a total count of emails you’ve sent with open tracking or link tracking enabled.

Triggers

postmark.triggers.inboundrules and postmark.triggers.tags, see Triggers.

InboundRulesManager

Bases: ModelManager[InboundRule]

all 

all(count=500, offset=0)

create 

create(Rule)

delete 

delete(id)

InboundRule

Bases: Model

delete 

delete()

TagsTriggersManager

Bases: ModelManager[Tag]

all 

all(count=500, offset=0, match_name=None)

get 

get(id)

create 

create(MatchName, TrackOpens=None)

edit 

edit(id, MatchName, TrackOpens=None)

delete 

delete(id)

Tag

Bases: BaseTag

get 

get()

edit 

edit(**kwargs)

delete 

delete()

Suppressions

postmark.suppressions, see Suppressions.

SuppressionsManager

Bases: ModelManager[Suppression]

Encapsulates logic about suppressions.

SubscriptionChange 

SubscriptionChange(json)

Constructs a :py:class:SubscriptionChange from the subscription change webhook payload.

Parameters:

Name Type Description Default
json str | bytes

str

 required

all 

all(
    stream_id=DEFAULT_STREAM_ID,
    SuppressionReason=None,
    Origin=None,
    fromdate=None,
    todate=None,
    EmailAddress=None,
)

Returns suppressed addresses of a message stream.

Parameters:

Name Type Description Default
stream_id str

Message stream ID.

 DEFAULT_STREAM_ID
SuppressionReason str

HardBounce, SpamComplaint or ManualSuppression.

 None
Origin str

Recipient, Customer or Admin.

 None
fromdate Any

Suppressed on or after this date.

 None
todate Any

Suppressed on or before this date.

 None
EmailAddress str

Email address.

 None

create 

create(emails, stream_id=DEFAULT_STREAM_ID)

Suppresses up to 50 addresses.

Parameters:

Name Type Description Default
emails list[str]

Email addresses.

 required
stream_id str

Message stream ID.

 DEFAULT_STREAM_ID

Returns:

Type Description
list[dict[str, Any]]

EmailAddress, Status (Suppressed or Failed) and Message per address.

delete 

delete(emails, stream_id=DEFAULT_STREAM_ID)

Reactivates up to 50 addresses. SpamComplaint suppressions can't be deleted.

Parameters:

Name Type Description Default
emails list[str]

Email addresses.

 required
stream_id str

Message stream ID.

 DEFAULT_STREAM_ID

Returns:

Type Description
list[dict[str, Any]]

EmailAddress, Status (Deleted or Failed) and Message per address.

SubscriptionChange

Bases: BaseSubscriptionChange, MessageModel

Subscription change webhook model: an address added to or removed from a suppression list.

message property 

message

Domains

postmark.domains, see Domains. Needs the account token.

DomainsManager

Bases: ModelManager[Domain]

all 

all(count=500, offset=0)

get 

get(id)

create 

create(Name, ReturnPathDomain=None)

edit 

edit(id, ReturnPathDomain)

delete 

delete(id)

verifyspf 

verifyspf(id)

verifydkim 

verifydkim(id)

verifyreturnpath 

verifyreturnpath(id)

rotatedkim 

rotatedkim(id)

Domain

Bases: BaseDomain

get 

get()

edit 

edit(**kwargs)

delete 

delete()

verifyspf 

verifyspf()

verifydkim 

verifydkim()

verifyreturnpath 

verifyreturnpath()

rotatedkim 

rotatedkim()