Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.paubox.com/llms.txt

Use this file to discover all available pages before exploring further.

​
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_      = 'sender@yourdomain.com',    # required
    subject    = 'Your results are ready',   # required
    recipients = ['alice@example.com'],       # 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':               'support@yourdomain.com',
        'cc':                     ['manager@example.com'],
        'bcc':                    'audit@example.com',      # 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:
PropertyDescription
.status_codeHTTP status code
.headersResponse headers dict
.textRaw response body as a string
.to_dictJSON-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