Email client

Full reference for the Paubox Python SDK email client: composing messages, sending email, tracking delivery, and error handling.

Instantiation

from paubox import PauboxApiClient

# Read credentials from environment variables
client = PauboxApiClient()

# Or pass credentials directly
client = PauboxApiClient(
    api_key = 'YOUR_API_KEY',
    host    = 'https://api.paubox.net/v1/YOUR_USERNAME'
)

See Authentication for both approaches.

Composing a message

Use the Mail helper to compose messages. It handles formatting and automatically base64-encodes HTML content before sending.

from paubox.helpers.mail import Mail

mail = Mail(
    from_      = '[e-mail]',    # required
    subject    = 'Your results are ready',   # required
    recipients = ['[e-mail]'],       # required; list of email strings
    content    = {                            # required; at least one key
        'text/plain': 'Plain text body.',
        'text/html':  '<p>HTML body.</p>'    # auto base64-encoded
    },
    optional_headers = {                      # optional
        'reply_to':               '[e-mail]',
        'cc':                     ['[e-mail]'],
        'bcc':                    '[e-mail]',      # str or list
        'allowNonTLS':            False,
        'forceSecureNotification': False,
        'attachments':            [attachment]
    }
)

Call mail.get() to get the formatted dict ready for the API.

Attachments

import base64

with open('report.pdf', 'rb') as f:
    encoded = base64.b64encode(f.read()).decode('utf-8')

attachment = {
    'fileName':    'report.pdf',
    'contentType': 'application/pdf',
    'content':     encoded
}

Pass attachments via the optional_headers dict:

optional_headers = {
    'attachments': [attachment]
}

Send a message

response = client.send(mail.get())
print('Status:', response.status_code)
print('Tracking ID:', response.to_dict.get('sourceTrackingId'))

Check delivery status

tracking_id = response.to_dict['sourceTrackingId']

disposition = client.get(tracking_id)
deliveries  = disposition.to_dict['data']['message']['message_deliveries']

for d in deliveries:
    print(d['recipient'], '→', d['status']['deliveryStatus'])

Common deliveryStatus values: delivered, opened, failed, pending.

The Response object

Both send and get return a Response object:

Property	Description
.status_code	HTTP status code
.headers	Response headers dict
.text	Raw response body as a string
.to_dict	JSON-parsed response body, or None if not JSON

Error handling

Both methods raise requests.exceptions.HTTPError on non-2xx responses. Wrap calls in a try/except block:

import requests

try:
    response = client.send(mail.get())
except requests.exceptions.HTTPError as e:
    print('API error:', e.response.status_code, e.response.text)

The optional handle_error helper prints the error response body before re-raising:

from paubox.helpers.errors import handle_error

try:
    response = client.send(mail.get())
except requests.exceptions.HTTPError as e:
    handle_error(e)  # prints body, then re-raises