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.