Open Source Ruby API to Check Email Tracking & Delivery Status

Getting Started with Postal

The easiest way to install the Postal library is via RubyGems. Please use the following command for easy installation.

 gem install 'postal-ruby'

Sending a Basic Email via Ruby API

The open source Postal APIs has included complete support for sending email messages in various ways. Ruby developers can send emails in multiple ways, catering to different levels of complexity. Simple Hash is perfect for quick sends with basic parameters. Plain text and HTML can be used to send multipart emails. It also support attaching files effortlessly to your email messages and so on. The following example demonstrates the simplest way to send an email.

# Create a client instance
client = Postal::Client.new

# Send a message using a hash of parameters
message = client.send_message(
  from: 'noreply@yourdomain.com',
  to: 'customer@example.com',
  subject: 'Welcome to Our Service!',
  body: 'Thank you for signing up. We are excited to have you on board.'
)

# The response contains the message ID, which you can use for tracking
puts "Message sent! ID: #{message.message_id}"

Check Email Tracking & Delivery Status

Monitor email opens and clicks to gauge the effectiveness of your campaigns. The Postal APIs has provide complete functionality for tracking y our email messages inside Ruby applications. After sending an email, you can use the returned message_id to check its current status. Monitor email opens and clicks to gauge the effectiveness of your campaigns. The following example shows how to check Email Message Delivery Status using Ruby commands.

# Assume you've stored the message_id from the send operation
stored_message_id = '01G5XYZABCDEF1234567890'

# Get the message details from Postal
message_details = client.get_message(stored_message_id)

# Check the delivery status
puts "Message Status: #{message_details.status}"

# Inspect the raw message (as received by the destination server)
puts "Raw Message: #{message_details.raw_message}"

# Check if the email has been opened
if message_details.opens.any?
  puts "The email was opened #{message_details.opens.count} time(s)."
end

Sending a Rich HTML Email with an Attachment

Modern emails often require HTML formatting and attachments. The open source Postal email API makes it easy for software developers to create and send Rich HTML Email messages from their Ruby applications. It's a best practice to always include a plain text version for email clients that don't support HTML. You can pass an array of File objects to attach documents, images, etc. Here is a very useful code sample that shows how software developers can create and send HTML email messages with attachments using Ruby API.

client = Postal::Client.new

message = client.send_message(
  from: 'orders@yourdomain.com',
  to: 'customer@example.com',
  subject: 'Your Order Confirmation #12345',
  html_body: File.read('path/to/order_confirmation.html'), # Load HTML from a file
  plain_body: 'Thank you for your order. Your order number is #12345.', # Fallback text
  attachments: [
    File.open('/path/to/invoice_12345.pdf') # Attach a file
  ]
)

puts "Rich email sent with attachment! ID: #{message.message_id}"