Skip to main content

​
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: '[email protected]',
  to: '[email protected]',
  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' => '[email protected]',
  'to' => ['[email protected]'],
  '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: '[email protected]',
  to: ['[email protected]', '[email protected]'],
  subject: 'Team Update',
  html: '<h1>Important Update</h1>',
  cc: ['[email protected]'],
  bcc: ['[email protected]'],
  reply_to: '[email protected]'
)

​
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: '[email protected]',
  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: '[email protected]',
    to: '[email protected]',
    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

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

​
Available Methods

MethodDescription
emails.send()Send an email
emails.get(id)Get email details by ID
emails.list()List all emails
domains.create(name)Add a domain
domains.verify(id)Verify domain DNS
domains.list()List all domains
domains.delete(id)Delete a domain
audiences.create(name)Create an audience
audiences.list()List all audiences
contacts.create(params)Add a contact to audience
contacts.list(audience_id)List contacts in audience
contacts.update(contact_id, params)Update a contact
contacts.delete(contact_id)Delete a contact
View on RubyGems: rubygems.org/gems/unosend

View full API reference

Explore all available API endpoints