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: - message (dict or
-
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:
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:
-
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: - bounce_id – The bounce’s id. Get the id with
-
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: - bounce_id – The bounce’s id. Get the id with
-
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: - bounce_id – The bounce’s id. Get the id with
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:
-
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:
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
- message (dict or
- message (dict or
-
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: - messages (A list of
- message (dict or
-
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
- message (dict or
- message (dict or
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:
-
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: - bounce_id – A bounce’s ID retrieved with
-
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: - bounce_id – A bounce’s ID retrieved with
-
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: - bounce_id – A bounce’s ID retrieved with
-
response_class
¶ alias of
BounceActivateResponse
- bounce_id – A bounce’s ID retrieved with
-
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_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_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:
-
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()
orMessage.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: TheMessage
to copy defaults from. :type other:Message
:param kwargs: Additional keyword arguments to constructMessage
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:
-
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()
andBatchSender.send()
Parameters: - response (
requests.Response
) – Response returned fromrequests.request()
. - sender (
Interface
) – The API interface wrapper that generated the request. Defaults to None.
- response (
-
class
pystmark.
BatchSendResponse
(response, sender=None)¶ Wrapper around
Sender.send()
andBatchSender.send()
Parameters: - response (
requests.Response
) – Response returned fromrequests.request()
. - sender (
Interface
) – The API interface wrapper that generated the request. Defaults to None.
- response (
-
class
pystmark.
BouncesResponse
(response, sender=None)¶ Wrapper for responses from
Bounces.get()
.Parameters: - response (
requests.Response
) – Response returned fromrequests.request()
. - sender (
Interface
) – The API interface wrapper that generated the request. Defaults to None.
- response (
-
class
pystmark.
BounceResponse
(response, sender=None)¶ Wrapper for responses from
Bounce.get()
.Parameters: - response (
requests.Response
) – Response returned fromrequests.request()
. - sender (
Interface
) – The API interface wrapper that generated the request. Defaults to None.
- response (
-
class
pystmark.
BounceDumpResponse
(response, sender=None)¶ Wrapper for responses from
BounceDump.get()
.Parameters: - response (
requests.Response
) – Response returned fromrequests.request()
. - sender (
Interface
) – The API interface wrapper that generated the request. Defaults to None.
- response (
-
class
pystmark.
BounceActivateResponse
(response, sender=None)¶ Wrapper for responses from the bounce activate endpoint.
Parameters: - response (
requests.Response
) – Response returned fromrequests.request()
. - sender (
Interface
) – The API interface wrapper that generated the request. Defaults to None.
- response (
-
class
pystmark.
BounceTagsResponse
(response, sender=None)¶ Wrapper for responses from
BounceTags.get()
.Parameters: - response (
requests.Response
) – Response returned fromrequests.request()
. - sender (
Interface
) – The API interface wrapper that generated the request. Defaults to None.
- response (
-
class
pystmark.
DeliveryStatsResponse
(response, sender=None)¶ Wrapper for responses from
BounceActivate.activate()
.Parameters: - response (
requests.Response
) – Response returned fromrequests.request()
. - sender (
Interface
) – The API interface wrapper that generated the request. Defaults to None.
- response (
-
class
pystmark.
OutboundMessageDetailsResponse
(response, sender=None)¶ Wrapper for responses from
OutboundMessageDetails.get()
.Parameters: - response (
requests.Response
) – Response returned fromrequests.request()
. - sender (
Interface
) – The API interface wrapper that generated the request. Defaults to None.
- response (
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: -
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()
.
- sender – A
-
-
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.
- response – A
Raised when Postmark responds with a
status_code
of 401 Indicates a missing or incorrect API key.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.
-
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 fromrequests.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
- response (