Skip to content

souravsspace/unsent-ruby

BranchesTags

Repository files navigation

Unsent Ruby SDK

Official Ruby SDK for the Unsent API - Send transactional emails with ease.

Prerequisites

Installation

Add this line to your application's Gemfile:

gem 'unsent'

And then execute:

bundle install

Or install it yourself as:

gem install unsent

Usage

Basic Setup

require 'unsent'

client = Unsent::Client.new('un_xxx')

Environment Variables

You can also set your API key using environment variables:

# Set UNSENT_API_KEY in your environment
# Then initialize without passing the key
client = Unsent::Client.new

Sending Emails

Simple Email

data, error = client.emails.send({
  to: 'user@example.com',
  from: 'no-reply@yourdomain.com',
  subject: 'Welcome',
  html: '<strong>Hello!</strong>'
})

if error
  puts "Error: #{error}"
else
  puts "Email sent! ID: #{data['id']}"
end

With Attachments and Scheduling

require 'time'

data, error = client.emails.create({
  to: 'user@example.com',
  from: 'no-reply@yourdomain.com',
  subject: 'Report',
  text: 'See attached.',
  attachments: [
    {
      filename: 'report.txt',
      content: 'SGVsbG8gd29ybGQ=' # base64
    }
  ],
  scheduledAt: (Time.now + 600).iso8601 # 10 minutes from now
})

Batch Send

emails = [
  {
    to: 'a@example.com',
    from: 'no-reply@yourdomain.com',
    subject: 'A',
    html: '<p>A</p>'
  },
  {
    to: 'b@example.com',
    from: 'no-reply@yourdomain.com',
    subject: 'B',
    html: '<p>B</p>'
  }
]

data, error = client.emails.batch(emails)
puts "Sent #{data['emails'].length} emails" if data

Idempotent Retries

To prevent duplicate emails when retrying failed requests, you can provide an idempotency key.

data, error = client.emails.send({
  to: 'user@example.com',
  from: 'no-reply@yourdomain.com',
  subject: 'Welcome',
  html: '<strong>Hello!</strong>'
}, {
  idempotency_key: 'unique-key-123'
})

Managing Emails

Get Email

email, error = client.emails.get('email_123')
puts "Email status: #{email['status']}" if email

Update Schedule

data, error = client.emails.update('email_123', {
  scheduledAt: (Time.now + 3600).iso8601 # 1 hour from now
})

Cancel Scheduled Email

data, error = client.emails.cancel('email_123')
puts 'Email cancelled successfully' if data

Contacts

Create Contact

data, error = client.contacts.create('book_123', {
  email: 'user@example.com',
  firstName: 'Jane',
  metadata: {
    plan: 'pro'
  }
})

Get Contact

contact, error = client.contacts.get('book_123', 'contact_456')

Update Contact

data, error = client.contacts.update('book_123', 'contact_456', {
  firstName: 'John',
  metadata: {
    plan: 'enterprise'
  }
})

Upsert Contact

data, error = client.contacts.upsert('book_123', 'contact_456', {
  email: 'user@example.com',
  firstName: 'Jane'
})

Delete Contact

data, error = client.contacts.delete('book_123', 'contact_456')

Campaigns

Create Campaign

data, error = client.campaigns.create({
  name: 'Welcome Series',
  subject: 'Welcome!',
  html: '<p>Thanks for joining us!</p>',
  from: 'welcome@yourdomain.com',
  contactBookId: 'book_123'
})

Schedule Campaign

data, error = client.campaigns.schedule('campaign_123', {
  scheduledAt: '2024-12-01T10:00:00Z'
})

Pause and Resume

# Pause
data, error = client.campaigns.pause('campaign_123')

# Resume
data, error = client.campaigns.resume('campaign_123')

Domains

List Domains

domains, error = client.domains.list
domains.each do |domain|
  puts "Domain: #{domain['domain']}, Status: #{domain['status']}"
end if domains

Create Domain

data, error = client.domains.create({
  domain: 'yourdomain.com'
})

Verify Domain

data, error = client.domains.verify(123)
puts "Verification status: #{data['status']}" if data

Error Handling

By default, the SDK raises Unsent::HTTPError for non-2xx responses:

begin
  data, error = client.emails.get('email_123')
rescue Unsent::HTTPError => e
  puts "HTTP #{e.status_code}: #{e.error['message']}"
end

To handle errors as return values instead:

client = Unsent::Client.new('un_xxx', raise_on_error: false)

data, error = client.emails.get('email_123')
if error
  puts "Error: #{error['message']}"
else
  puts "Success!"
end

Email Management

List Emails

Retrieve a paginated list of emails with optional filters:

data, error = client.emails.list(
  page: 1,
  limit: 10,
  startDate: '2024-01-01',
  endDate: '2024-01-31',
  domainId: 'domain_123'
)

# Support for multiple domain IDs
data, error = client.emails.list(domainId: ['domain_1', 'domain_2'])

Email Statistics

# Get complaints
data, error = client.emails.get_complaints(page: 1, limit: 10)

# Get bounces
data, error = client.emails.get_bounces(page: 1, limit: 10)

# Get unsubscribes
data, error = client.emails.get_unsubscribes(page: 1, limit: 10)

# Get events for a specific email
events, error = client.emails.get_events('email_123', page: 1, limit: 10)
if events
  events['data'].each do |event|
    puts "Event: #{event['type']} at #{event['timestamp']}"
  end
end

Domains

Manage your sending domains and retrieve domain-specific analytics.

Domain Analytics & Statistics

# Get analytics for a specific domain
data, error = client.domains.get_analytics('domain_123', days: 30)
puts "Total sent: #{data['sent']}, Delivered: #{data['delivered']}" if data

# Get analytics with custom date range
data, error = client.domains.get_analytics(
  'domain_123',
  startDate: '2024-01-01',
  endDate: '2024-01-31'
)

# Get domain statistics
stats, error = client.domains.get_stats('domain_123', days: 7)
puts "Bounce rate: #{stats['bounceRate']}%" if stats

# Get stats with custom date range
stats, error = client.domains.get_stats(
  'domain_123',
  startDate: '2024-01-01',
  endDate: '2024-01-15'
)

Domain Management

List Domains

domains, error = client.domains.list
domains.each do |domain|
  puts "Domain: #{domain['domain']}, Status: #{domain['status']}"
end if domains

Create Domain

data, error = client.contact_books.create(
  name: 'Newsletter Subscribers',
  emoji: '📧'
)

List Contact Books

books, error = client.contact_books.list
books.each { |book| puts book['name'] }

Get Contact Book

book, error = client.contact_books.get('book_123')

Update Contact Book

data, error = client.contact_books.update('book_123', name: 'Updated Name')

Delete Contact Book

data, error = client.contact_books.delete('book_123')

Contacts

List Contacts

data, error = client.contacts.list('book_123',
  page: 1,
  limit: 10,
  search: 'john@example.com'
)

Campaigns

List Campaigns

campaigns, error = client.campaigns.list

Analytics

Get insights into your email sending performance.

Overall Analytics

data, error = client.analytics.get
puts "Sent: #{data['sent']}, Delivered: #{data['delivered']}"

Time Series Data

data, error = client.analytics.get_time_series(
  days: 30,
  domain: 'yourdomain.com'
)

Reputation Score

data, error = client.analytics.get_reputation(domain: 'yourdomain.com')
puts "Reputation Score: #{data['score']}"

Templates

Manage reusable email templates.

Create Template

data, error = client.templates.create(
  name: 'Welcome Email',
  subject: 'Welcome to {{companyName}}!',
  html: '<h1>Welcome {{firstName}}!</h1>'
)

List Templates

templates, error = client.templates.list

Get Template

template, error = client.templates.get('template_123')

Update Template

data, error = client.templates.update('template_123',
  subject: 'Updated Subject'
)

Delete Template

data, error = client.templates.delete('template_123')

Suppressions

Manage your email suppression list.

List Suppressions

data, error = client.suppressions.list(
  page: 1,
  limit: 10,
  reason: 'MANUAL',
  search: 'user@'
)

Add to Suppression List

data, error = client.suppressions.add(
  email: 'blocked@example.com',
  reason: 'MANUAL'
)

Remove from Suppression List

data, error = client.suppressions.delete('blocked@example.com')

API Keys

Manage your API keys programmatically.

List API Keys

keys, error = client.api_keys.list

Create API Key

data, error = client.api_keys.create(
  name: 'Production Key',
  permission: 'SENDING'
)
puts "New key: #{data['key']}"

Delete API Key

data, error = client.api_keys.delete('key_123')

Webhooks

Note: Webhooks are currently a future feature and are documented here for reference.

Configure webhooks to receive real-time notifications.

List Webhooks

webhooks, error = client.webhooks.list

Create Webhook

data, error = client.webhooks.create(
  url: 'https://yourdomain.com/webhooks',
  events: ['email.sent', 'email.delivered', 'email.bounced']
)

Update Webhook

data, error = client.webhooks.update('webhook_123',
  url: 'https://yourdomain.com/updated-webhook'
)

Delete Webhook

data, error = client.webhooks.delete('webhook_123')

Settings

Retrieve account settings.

settings, error = client.settings.get

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/souravsspace/unsent-ruby.

License

The gem is available as open source under the terms of the MIT License.

About

No description, website, or topics provided.

Resources

Readme

License

MIT license

Code of conduct

Code of conduct
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

3 tags

Packages

 
 
 

Contributors

Languages