Email client

Full reference for the Paubox Ruby SDK email client: building messages, sending email, tracking delivery, dynamic templates, and error handling.

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:                    '[e-mail]',  # required
  to:                      ['[e-mail]'],    # required; array
  subject:                 'Your results are ready', # optional
  reply_to:                '[e-mail]', # optional
  cc:                      ['[e-mail]'],  # optional
  bcc:                     ['[e-mail]'],    # 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:

Field	Description
source_tracking_id	The tracking ID
message_deliveries	Array of MessageDelivery structs
errors	Array 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:    '[e-mail]',
  to:      ['[e-mail]'],
  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