Simple API

Sending Email

pystmark.send(message, api_key=None, secure=None, test=None, **request_args)

Send a message.

Parameters:
  • message (dict or Message) – Message to send.
  • api_key – Your Postmark API key. Required, if test is not True.
  • secure – Use the https scheme for the Postmark API. Defaults to True
  • test – Use the Postmark Test API. Defaults to False.
  • request_args – Keyword arguments to pass to requests.request().
Return type:

SendResponse

pystmark.send_batch(messages, api_key=None, secure=None, test=None, **request_args)

Send a batch of messages.

Parameters:
  • messages – Messages to send.
  • api_key – Your Postmark API key. Required, if test is not True.
  • secure – Use the https scheme for the Postmark API. Defaults to True
  • test – Use the Postmark Test API. Defaults to False.
  • request_args – Keyword arguments to pass to requests.request().
Return type:

BatchSendResponse

Bounce Handling

pystmark.get_bounces(api_key=None, secure=None, test=None, **request_args)

Get a paginated list of bounces.

Parameters:
  • api_key – Your Postmark API key. Required, if test is not True.
  • secure – Use the https scheme for the Postmark API. Defaults to True
  • test – Use the Postmark Test API. Defaults to False.
  • request_args – Keyword arguments to pass to requests.request().
Return type:

BouncesResponse

pystmark.get_bounce(bounce_id, api_key=None, secure=None, test=None, **request_args)

Get a single bounce.

Parameters:
  • bounce_id – The bounce’s id. Get the id with get_bounces().
  • api_key – Your Postmark API key. Required, if test is not True.
  • secure – Use the https scheme for the Postmark API. Defaults to True
  • test – Use the Postmark Test API. Defaults to False.
  • request_args – Keyword arguments to pass to requests.request().
Return type:

BounceResponse

pystmark.get_bounce_dump(bounce_id, api_key=None, secure=None, test=None, **request_args)

Get the raw email dump for a single bounce.

Parameters:
  • bounce_id – The bounce’s id. Get the id with get_bounces().
  • api_key – Your Postmark API key. Required, if test is not True.
  • secure – Use the https scheme for the Postmark API. Defaults to True
  • test – Use the Postmark Test API. Defaults to False.
  • request_args – Keyword arguments to pass to requests.request().
Return type:

BounceDumpResponse

pystmark.activate_bounce(bounce_id, api_key=None, secure=None, test=None, **request_args)

Activate a deactivated bounce.

Parameters:
  • bounce_id – The bounce’s id. Get the id with get_bounces().
  • api_key – Your Postmark API key. Required, if test is not True.
  • secure – Use the https scheme for the Postmark API. Defaults to True
  • test – Use the Postmark Test API. Defaults to False.
  • request_args – Keyword arguments to pass to requests.request().
Return type:

BounceActivateResponse

pystmark.get_bounce_tags(api_key=None, secure=None, test=None, **request_args)

Get a list of tags for bounces associated with your Postmark server.

Parameters:
  • api_key – Your Postmark API key. Required, if test is not True.
  • secure – Use the https scheme for the Postmark API. Defaults to True
  • test – Use the Postmark Test API. Defaults to False.
  • request_args – Keyword arguments to pass to requests.request().
Return type:

BounceTagsResponse

pystmark.get_delivery_stats(api_key=None, secure=None, test=None, **request_args)

Get delivery stats for your Postmark account.

Parameters:
  • api_key – Your Postmark API key. Required, if test is not True.
  • secure – Use the https scheme for the Postmark API. Defaults to True
  • test – Use the Postmark Test API. Defaults to False.
  • request_args – Keyword arguments to pass to requests.request().
Return type:

DeliveryStatsResponse

Advanced API

Sending Email

class pystmark.Sender(message=None, api_key=None, secure=True, test=False)

Sends a single message via the Postmark API.

All of the arguments used in constructing this object are used as defaults in the final call to Sender.send(). You can override any of them at that time.

Parameters:
  • message (dict or Message) – Default message data, such as sender and reply_to.
  • api_key – Your Postmark API key.
  • secure – Use the https scheme for Postmark API. Defaults to True
  • test – Make a test request to the Postmark API. Defaults to False.
response_class

alias of SendResponse

send(message=None, api_key=None, secure=None, test=None, **request_args)

Send request to Postmark API. Returns result of requests.post().

Parameters:
  • message (dict or Message) – Your Postmark message data.
  • api_key (str) – Your Postmark API key.
  • test – Make a test request to the Postmark API.
  • secure – Use the https Postmark API.
  • request_args – Passed to requests.post()
Return type:

requests.Response

class pystmark.BatchSender(message=None, api_key=None, secure=True, test=False)

Sends a batch of messages via the Postmark API.

All of the arguments used in constructing this object are used as defaults in the final call to BatchSender.send(). You can override any of them at that time.

Parameters:
  • message (dict or Message) – Default message data, such as sender and reply_to.
  • api_key – Your Postmark API key.
  • secure – Use the https scheme for Postmark API. Defaults to True
  • test – Make a test request to the Postmark API. Defaults to False.
response_class

alias of BatchSendResponse

send(messages=None, api_key=None, secure=None, test=None, **request_args)

Send batch request to Postmark API. Returns result of requests.post().

Parameters:
  • messages (A list of Message) – Batch messages to send to the Postmark API.
  • api_key – Your Postmark API key. Defaults to self.api_key.
  • test – Make a test request to the Postmark API. Defaults to self.test.
  • secure – Use the https Postmark API. Defaults to self.secure.
  • request_args – Passed to requests.request()
Return type:

BatchSendResponse

class pystmark.TemplateSender(message=None, api_key=None, secure=True, test=False)

Sends a single message via the Postmark API with template.

All of the arguments used in constructing this object are used as defaults in the final call to Sender.send(). You can override any of them at that time.

Parameters:
  • message (dict or Message) – Default message data, such as sender and reply_to.
  • api_key – Your Postmark API key.
  • secure – Use the https scheme for Postmark API. Defaults to True
  • test – Make a test request to the Postmark API. Defaults to False.
response_class

alias of SendResponse

send(message=None, api_key=None, secure=None, test=None, **request_args)

Send request to Postmark API. Returns result of requests.post().

Parameters:
  • message (dict or Message) – Your Postmark message data.
  • api_key (str) – Your Postmark API key.
  • test – Make a test request to the Postmark API.
  • secure – Use the https Postmark API.
  • request_args – Passed to requests.post()
Return type:

requests.Response

Bounce Handling

class pystmark.Bounces(api_key=None, secure=True, test=False)

Multiple bounce retrieval endpoint wrapper.

Parameters:
  • api_key – Your Postmark API key. Defaults to None.
  • secure – Use the https scheme for Postmark API. Defaults to True.
  • test – Make a test request to the Postmark API. Defaults to False.
get(bounce_type=None, inactive=None, email_filter=None, message_id=None, count=None, offset=None, api_key=None, secure=None, test=None, **request_args)

Builds query string params from inputs. It handles offset and count defaults and validation.

Parameters:
  • bounce_type – The type of bounces retrieve. See bounce_types for a list of types, or read the Postmark API docs. Defaults to None.
  • inactive – If True, retrieves inactive bounces only. Defaults to None.
  • email_filter – A string to filter emails by. Defaults to None.
  • message_id – Retrieve a bounce for a single message’s ID. Defaults to None.
  • count – The number of bounces to retrieve in this request. Defaults to 25 if message_id is not provided.
  • offset – The page offset for bounces to retrieve. Defaults to 0 if message_id is not provided.
  • api_key – Your Postmark API key. Defaults to self.api_key.
  • secure – Use the https scheme for Postmark API. Defaults to self.secure.
Params test:

Use the Postmark test API. Defaults to self.test.

Return type:

BouncesResponse

response_class

alias of BouncesResponse

class pystmark.Bounce(api_key=None, secure=True, test=False)

Single bounce retrieval endpoint wrapper.

Parameters:
  • api_key – Your Postmark API key. Defaults to None.
  • secure – Use the https scheme for Postmark API. Defaults to True.
  • test – Make a test request to the Postmark API. Defaults to False.
get(bounce_id, api_key=None, secure=None, test=None, **request_args)

Retrieves a single bounce’s data.

Parameters:
  • bounce_id – A bounce’s ID retrieved with Bounces.
  • api_key – Your Postmark API key. Defaults to self.api_key.
  • secure – Use the https scheme for Postmark API. Defaults to self.secure.
  • test – Make a test request to the Postmark API. Defaults to self.test.
  • request_args – Keyword args to pass to requests.request().
Return type:

BounceResponse

response_class

alias of BounceResponse

class pystmark.BounceDump(api_key=None, secure=True, test=False)

Bounce dump endpoint wrapper.

get(bounce_id, api_key=None, secure=None, test=None, **request_args)

Retrieves a single bounce’s data.

Parameters:
  • bounce_id – A bounce’s ID retrieved with Bounces.
  • api_key – Your Postmark API key. Defaults to self.api_key.
  • secure – Use the https scheme for Postmark API. Defaults to self.secure.
  • test – Make a test request to the Postmark API. Defaults to self.test.
  • request_args – Keyword args to pass to requests.request().
Return type:

BounceResponse

response_class

alias of BounceDumpResponse

class pystmark.BounceActivate(api_key=None, secure=True, test=False)

Bounce Activation endpoint wrapper.

Parameters:
  • bounce_id – A bounce’s ID retrieved with Bounces. Defaults to None.
  • api_key – Your Postmark API key. Defaults to None.
  • secure – Use the https scheme for Postmark API. Defaults to True.
  • test – Make a test request to the Postmark API. Defaults to False.
activate(bounce_id, api_key=None, secure=None, test=None, **request_args)

Activates a bounce.

Parameters:
  • bounce_id – A bounce’s ID retrieved with Bounces.
  • api_key – Your Postmark API key. Defaults to self.api_key.
  • secure – Use the https scheme for Postmark API. Defaults to self.secure.
  • test – Make a test request to the Postmark API. Defaults to self.test.
  • request_args – Keyword args to pass to requests.request().
Return type:

BounceActivateResponse

response_class

alias of BounceActivateResponse

class pystmark.BounceTags(api_key=None, secure=True, test=False)

Bounce tags endpoint wrapper.

get(api_key=None, secure=None, test=None, **request_args)

Make a GET request to the Postmark API

Parameters:
  • api_key – Your Postmark API key.
  • secure – Use the https scheme for Postmark API. Defaults to True
  • test – Make a test request to the Postmark API. Defaults to False.
  • request_args – Keyword arguments to pass to requests.request().
Return type:

Response

response_class

alias of BounceTagsResponse

class pystmark.DeliveryStats(api_key=None, secure=True, test=False)

Delivery Stats endpoint wrapper.

get(api_key=None, secure=None, test=None, **request_args)

Make a GET request to the Postmark API

Parameters:
  • api_key – Your Postmark API key.
  • secure – Use the https scheme for Postmark API. Defaults to True
  • test – Make a test request to the Postmark API. Defaults to False.
  • request_args – Keyword arguments to pass to requests.request().
Return type:

Response

response_class

alias of DeliveryStatsResponse

Message Details

class pystmark.OutboundMessageDetails(api_key=None, secure=True, test=False)

Outbound message details endpoint wrapper.

get(message_id, api_key=None, secure=None, test=None, **request_args)

Retrieves a single messages’s data.

Parameters:
  • message_id – A messages’s ID.
  • api_key – Your Postmark API key. Defaults to self.api_key.
  • secure – Use the https scheme for Postmark API. Defaults to self.secure.
  • test – Make a test request to the Postmark API. Defaults to self.test.
  • request_args – Keyword args to pass to requests.request().
Return type:

OutboundMessageDetailsResponse

response_class

alias of OutboundMessageDetailsResponse

Message Object

class pystmark.Message(sender=None, to=None, cc=None, bcc=None, subject=None, template_id=None, template_alias=None, template_model=None, tag=None, html=None, text=None, reply_to=None, headers=None, attachments=None, verify=False, track_opens=None)

A container for message(s) to send to the Postmark API. You can populate this message with defaults for initializing an Interface. The message will be combined with the final message and verified before transmission.

Parameters:
  • sender – Email address of the sender.
  • to – Destination email address.
  • cc – A list of cc’d email addresses.
  • bcc – A list of bcc’d email address.
  • subject – The message subject.
  • tag – Tag your emails with this.
  • html – HTML body content.
  • text – Text body content.
  • reply_to – Email address to reply to.
  • headers (A list of dict, each with the keys ‘Name’ and ‘Value’.) – Additional headers to include with the email. If you do not have the headers formatted for the Postmark API, use Message.add_header().
  • attachments (A list of dict, each with the keys ‘Name’, ‘Content’ and ‘ContentType’.) – Attachments to include with the email. If you do not have the attachments formatted for the Postmark API, use Message.attach_file() or Message.attach_binary().
  • verify – Verify the message when initialized. Defaults to False.
  • track_opens – Set to true to enable tracking email opens.
add_header(name, value)

Attach an email header to send with the message.

Parameters:
  • name – The name of the header value.
  • value – The header value.
attach_binary(data, filename, content_type=None, content_id=None)

Attach a file to the message given raw binary data.

Parameters:
  • data – Raw data to attach to the message.
  • filename – Name of the file for the data.
  • content_type – mimetype of the data. It will be guessed from the filename if not provided.
  • content_id – ContentID URL of the attachment. A RFC 2392- compliant URL for the attachment that allows it to be referenced from inside the body of the message. Must start with ‘cid:’
attach_file(filename, content_type=None, content_id=None)

Attach a file to the message given a filename.

Parameters:
  • filename – Name of the file to attach.
  • content_type – mimetype of the data. It will be guessed from the filename if not provided.
  • content_id – ContentID URL of the attachment. A RFC 2392- compliant URL for the attachment that allows it to be referenced from inside the body of the message. Must start with ‘cid:’
bcc

A comma delimited string of receivers for the message ‘Bcc’ field.

cc

A comma delimited string of receivers for the message ‘Cc’ field.

data()

Returns data formatted for a POST request to the Postmark send API.

Return type:dict
json()

Return json-encoded string of message data.

Return type:str
load_from(other, **kwargs)

Create a Message by merging other with self. Values from other will be copied to self if the value was not set on self and is set on other. :param other: The Message to copy defaults from. :type other: Message :param kwargs: Additional keyword arguments to construct

Message with.
Return type:Message
classmethod load_message(message, **kwargs)

Create a Message from a message data dict.

Parameters:
  • message – A dict of message data.
  • kwargs – Additional keyword arguments to construct Message with.
Return type:

Message

recipients

A list of all recipients for this message.

to

A comma delimited string of receivers for the message ‘To’ field.

verify()

Verifies the message data based on rules and restrictions defined in the Postmark API docs. There can be no more than 20 recipients in total. NOTE: This does not check that your attachments total less than 10MB, you must do that yourself.

Response Objects

class pystmark.SendResponse(response, sender=None)

Wrapper around Sender.send() and BatchSender.send()

Parameters:
  • response (requests.Response) – Response returned from requests.request().
  • sender (Interface) – The API interface wrapper that generated the request. Defaults to None.
class pystmark.BatchSendResponse(response, sender=None)

Wrapper around Sender.send() and BatchSender.send()

Parameters:
  • response (requests.Response) – Response returned from requests.request().
  • sender (Interface) – The API interface wrapper that generated the request. Defaults to None.
class pystmark.BouncesResponse(response, sender=None)

Wrapper for responses from Bounces.get().

Parameters:
  • response (requests.Response) – Response returned from requests.request().
  • sender (Interface) – The API interface wrapper that generated the request. Defaults to None.
class pystmark.BounceResponse(response, sender=None)

Wrapper for responses from Bounce.get().

Parameters:
  • response (requests.Response) – Response returned from requests.request().
  • sender (Interface) – The API interface wrapper that generated the request. Defaults to None.
class pystmark.BounceDumpResponse(response, sender=None)

Wrapper for responses from BounceDump.get().

Parameters:
  • response (requests.Response) – Response returned from requests.request().
  • sender (Interface) – The API interface wrapper that generated the request. Defaults to None.
class pystmark.BounceActivateResponse(response, sender=None)

Wrapper for responses from the bounce activate endpoint.

Parameters:
  • response (requests.Response) – Response returned from requests.request().
  • sender (Interface) – The API interface wrapper that generated the request. Defaults to None.
class pystmark.BounceTagsResponse(response, sender=None)

Wrapper for responses from BounceTags.get().

Parameters:
  • response (requests.Response) – Response returned from requests.request().
  • sender (Interface) – The API interface wrapper that generated the request. Defaults to None.
class pystmark.DeliveryStatsResponse(response, sender=None)

Wrapper for responses from BounceActivate.activate().

Parameters:
  • response (requests.Response) – Response returned from requests.request().
  • sender (Interface) – The API interface wrapper that generated the request. Defaults to None.
class pystmark.OutboundMessageDetailsResponse(response, sender=None)

Wrapper for responses from OutboundMessageDetails.get().

Parameters:
  • response (requests.Response) – Response returned from requests.request().
  • sender (Interface) – The API interface wrapper that generated the request. Defaults to None.

Response Data Wrappers

class pystmark.MessageConfirmation(data)

Wrapper around data returned from Postmark after sending

Parameters:data – Data returned from Postmark upon sending a message
class pystmark.BouncedMessage(bounce_data, sender=None)

Bounced message data wrapper.

Parameters:
  • bounce_data – Raw bounced message data retrieved from Bounce or Bounces.
  • sender – The Interface that made the request for the bounce data. Defaults to None.
dump(sender=None, **kwargs)

Retrieve raw email dump for this bounce.

Parameters:
  • sender – A BounceDump object to get dump with. Defaults to None.
  • kwargs – Keyword arguments passed to requests.request().
class pystmark.BounceTypeData(bounce_type_data)

Bounce type data wrapper.

Parameters:bounce_type_data – Raw bounce type data retrieved from DeliveryStats.

Exceptions

class pystmark.PystmarkError(message=None)

Base Exception for pystmark errors.

Parameters:message – Message to raise with the Exception. Defaults to None.
with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

class pystmark.MessageError(message=None)

Raised when a message meant to be sent to Postmark API looks malformed

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

class pystmark.BounceError(message=None)

Raised when a bounce API method fails

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

class pystmark.ResponseError(response, message=None)

Base Exception for errors received from Postmark API

Parameters:
  • response – A Response.
  • message – Message to raise with the Exception. Defaults to None.
with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

class pystmark.UnauthorizedError(response, message=None)

Raised when Postmark responds with a status_code of 401 Indicates a missing or incorrect API key.

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

class pystmark.UnprocessableEntityError(response, message=None)

Raised when Postmark responds with a status_code of 422. Indicates message(s) received by Postmark were malformed.

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

class pystmark.InternalServerError(response, message=None)

Raised when Postmark responds with a status_code of 500 Indicates an error on Postmark’s end. Any messages sent in the request were not received by them.

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

Base Classes

class pystmark.Interface(api_key=None, secure=True, test=False)

Base class interface for Postmark API endpoint wrappers

Parameters:
  • api_key – Your Postmark API key. Defaults to None.
  • secure – Use the https scheme for API requests. Defaults to True.
  • test – Use the Postmark test API. Defaults to False.
response_class

alias of Response

class pystmark.Response(response, sender=None)

Base class for API response wrappers. The wrapped requests.Response object interface is exposed by this class, unless the attribute is defined in self._attrs.

Parameters:
  • response (requests.Response) – Response returned from requests.request().
  • sender (Interface) – The API interface wrapper that generated the request. Defaults to None.
raise_for_status()

Raise Postmark-specific HTTP errors. If there isn’t one, the standard HTTP error is raised.

HTTP 401 raises UnauthorizedError

HTTP 422 raises UnprocessableEntityError

HTTP 500 raises InternalServerError