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.

​
The client

client = Paubox::Client.new          # uses global Paubox.configure credentials
client = Paubox::Client.new(         # or per-client credentials
  api_key:  'YOUR_API_KEY',
  api_user: 'YOUR_USERNAME'
)
send_mail and deliver_mail are aliases. email_disposition and message_receipt are aliases.

​
Building a message

message = Paubox::Message.new(
  from:                    'sender@yourdomain.com',  # required
  to:                      ['alice@example.com'],    # required; array
  subject:                 'Your results are ready', # optional
  reply_to:                'support@yourdomain.com', # optional
  cc:                      ['manager@example.com'],  # optional
  bcc:                     ['audit@example.com'],    # optional
  text_content:            'Plain text body.',       # at least one required
  html_content:            '<p>HTML body.</p>',      # optional
  allow_non_tls:           false,                    # optional; default false
  force_secure_notification: false                   # optional; default false
)

​
Attachments

Attach files by path using the helper method: 
message.add_attachment('/path/to/report.pdf')
Or set the attachments attribute directly with an array of hashes (each with fileName, contentType, and base64-encoded content): 
require 'base64'

message.attachments = [
  {
    fileName:    'report.pdf',
    contentType: 'application/pdf',
    content:     Base64.strict_encode64(File.read('/path/to/report.pdf'))
  }
]

​
Send a message

response = client.send_mail(message)
puts response[:source_tracking_id]

​
Check delivery status

disposition = client.email_disposition(source_tracking_id)

disposition.message_deliveries.each do |delivery|
  puts "#{delivery.recipient} → #{delivery.status.delivery_status}"
  puts "  Opened: #{delivery.status.opened_status}"
end
EmailDisposition fields:
FieldDescription
source_tracking_idThe tracking ID
message_deliveriesArray of MessageDelivery structs
errorsArray of ResponseError structs
Each MessageDelivery struct has recipient and status. The status struct has delivery_status, delivery_time, opened_status, and opened_time. Check disposition.errors? to detect API-level errors. Common delivery_status values: delivered, opened, failed, pending.

​
Dynamic templates

Templates use Handlebars syntax ({{variable_name}}).

​
Create a template

Paubox::DynamicTemplates.create('appointment-confirmation', '/path/to/template.html')

​
List templates

templates = Paubox::DynamicTemplates.list
templates.each { |t| puts "#{t[:id]}: #{t[:name]}" }

​
Get a template

template = Paubox::DynamicTemplates.find(template_id)

​
Update a template

template.update('/path/to/updated-template.html')
# or rename:
template.update('/path/to/updated-template.html', 'new-template-name')

​
Delete a template

template.delete

​
Send a templated message

message = Paubox::TemplatedMessage.new(
  from:    'appointments@yourclinic.com',
  to:      ['jane@example.com'],
  subject: 'Your appointment is confirmed',
  template: {
    name:   'appointment-confirmation',
    values: {
      first_name: 'Jane',
      date:       '2024-03-15',
      time:       '2:00 PM'
    }
  }
)

response = client.send_mail(message)

​
Error handling

Methods raise RestClient::ExceptionWithResponse on HTTP errors. Rescue it to inspect the response: 
require 'rest-client'

begin
  response = client.send_mail(message)
rescue RestClient::ExceptionWithResponse => e
  puts "HTTP #{e.response.code}: #{e.response.body}"
end