Command Palette

Search for a command to run...

SDK

Ruby SDK

The official Ruby SDK for Unosend. Supports Ruby 2.7+ with idiomatic patterns.

Installation

Add this line to your application's Gemfile:

Gemfile
gem 'unosend'

Then execute:

terminal
bundle install

Or install directly:

terminal
gem install unosend

Requirements

  • Ruby 2.7 or higher

Environment Variables

Never hardcode your API key. Use environment variables instead:

.env
UNOSEND_API_KEY=un_your_api_key
app.rb
require 'unosend'

client = Unosend::Client.new(ENV['UNOSEND_API_KEY'])

Basic Usage

send_email.rb
require 'unosend'

client = Unosend::Client.new('un_your_api_key')

# Send an email
email = client.emails.send(
  from: 'hello@yourdomain.com',
  to: 'user@example.com',
  subject: 'Welcome!',
  html: '<h1>Hello!</h1><p>Welcome to our platform.</p>'
)

puts "Email sent: #{email['id']}"

Response Format

All SDK methods return a hash with the response data:

response.rb
# Successful response
email = client.emails.send(...)

# Response hash
{
  'id' => 'em_xxxxxxxxxxxxxxxxxxxxxxxx',
  'from' => 'hello@yourdomain.com',
  'to' => ['user@example.com'],
  'subject' => 'Welcome!',
  'status' => 'queued',
  'created_at' => '2024-01-15T10:30:00Z'
}

# Access response data
puts email['id']
puts email['status']

Send to Multiple Recipients

multiple.rb
email = client.emails.send(
  from: 'hello@yourdomain.com',
  to: ['user1@example.com', 'user2@example.com'],
  subject: 'Team Update',
  html: '<h1>Important Update</h1>',
  cc: ['manager@example.com'],
  bcc: ['archive@example.com'],
  reply_to: 'support@yourdomain.com'
)

Working with Domains

domains.rb
# Add a domain
domain = client.domains.create('yourdomain.com')
puts "Domain added: #{domain['id']}"
puts "DNS Records: #{domain['records']}"

# List all domains
domains = client.domains.list
domains.each do |d|
  puts "#{d['name']} - #{d['status']}"
end

# Verify domain DNS
domain = client.domains.verify(domain_id)
puts "Domain status: #{domain['status']}"

# Delete a domain
client.domains.delete(domain_id)

Working with Audiences & Contacts

audiences.rb
# Create an audience
audience = client.audiences.create('Newsletter Subscribers')
puts "Audience created: #{audience['id']}"

# Add a contact to the audience
contact = client.contacts.create(
  audience_id: audience['id'],
  email: 'user@example.com',
  first_name: 'John',
  last_name: 'Doe'
)
puts "Contact added: #{contact['id']}"

# List contacts
contacts = client.contacts.list(audience['id'])
contacts.each do |c|
  puts "#{c['email']} - #{c['first_name']}"
end

# Update a contact
contact = client.contacts.update(contact_id,
  first_name: 'Jane',
  unsubscribed: false
)

# Delete a contact
client.contacts.delete(contact_id)

Error Handling

errors.rb
begin
  email = client.emails.send(
    from: 'hello@yourdomain.com',
    to: 'user@example.com',
    subject: 'Test',
    html: '<p>Hello</p>'
  )
  
  puts "Success! Email ID: #{email['id']}"
rescue Unosend::Error => e
  puts "Error #{e.code}: #{e.message}"
  
  # Handle specific error codes
  case e.code
  when 401
    puts "Invalid API key"
  when 429
    puts "Rate limit exceeded"
  end
end

Custom Configuration

config.rb
# Custom base URL (for self-hosted instances)
client = Unosend::Client.new('un_your_api_key',
  base_url: 'https://your-instance.com/api/v1'
)

Rails Integration

config/initializers/unosend.rb
# config/initializers/unosend.rb
UNOSEND_CLIENT = Unosend::Client.new(
  Rails.application.credentials.unosend_api_key
)
app/services/email_service.rb
# app/services/email_service.rb
class EmailService
  def self.send_welcome_email(user)
    UNOSEND_CLIENT.emails.send(
      from: 'hello@yourdomain.com',
      to: user.email,
      subject: "Welcome, #{user.name}!",
      html: "<h1>Hello #{user.name}</h1><p>Welcome to our platform!</p>"
    )
  end
end