Keplars Email SDK for Ruby

Official Ruby SDK for the Keplars Email API - modern transactional email service with priority-based delivery.

Installation

Add this line to your application's Gemfile:

gem 'keplars'

And then execute:

bundle install

Or install it yourself as:

gem install keplars

Quick Start

require 'keplars'

client = Keplars::Client.new(api_key: 'kms_<workspaceId>.live_<secret>')

result = client.emails.send_instant(
  from: 'noreply@yourdomain.com',
  to: 'user@example.com',
  subject: 'Your verification code is 123456',
  html: '<p>Your verification code is <strong>123456</strong></p>'
)

puts result[:data][:job_id]

API Key Types

Type	Format	Used for
Regular	kms_<id>.live_<secret>	Email sending
Admin	kms_<id>.adm_<secret>	Contacts, audiences, automations, domains

Email Sending

Priority Levels

Method	Delivery	Use case
send_instant	0–5 sec	OTPs, login codes, critical alerts
send_high	0–30 sec	Transactional, notifications
send_async / send	0–5 min	General transactional
send_bulk	Idle	Newsletters, marketing

Send with Recipients

result = client.emails.send_high(
  from: 'noreply@yourdomain.com',
  to: [{ email: 'user@example.com', name: 'John Doe' }],
  cc: [{ email: 'manager@example.com' }],
  subject: 'Order Confirmation',
  html: '<p>Your order has been confirmed</p>'
)

Response Shape

result[:success]           # true
result[:message]           # 'Email queued'
result[:data][:job_id]     # 'job_abc123'
result[:data][:priority]   # 'high'

Send with Template

result = client.emails.send(
  from: 'noreply@yourdomain.com',
  to: 'user@example.com',
  subject: 'Password Reset',
  template_id: 'tpl_reset_password',
  template_data: {
    name: 'John',
    reset_link: 'https://example.com/reset/abc'
  }
)

Schedule Email

result = client.emails.schedule(
  from: 'newsletter@yourdomain.com',
  to: 'user@example.com',
  subject: 'Your weekly digest',
  html: '<p>Here is your weekly digest...</p>',
  scheduled_for: '2026-06-01T09:00:00Z',
  priority: 'bulk'
)

Contacts (Admin API Key Required)

admin_client = Keplars::Client.new(api_key: 'kms_<workspaceId>.adm_<secret>')

admin_client.contacts.add(email: 'user@example.com', name: 'John Doe', audience_id: 'aud_abc123')

contact = admin_client.contacts.get('user@example.com')

contacts = admin_client.contacts.list(audience_id: 'aud_abc123', page: 1, limit: 20)

admin_client.contacts.update('user@example.com', name: 'Jane Doe')

admin_client.contacts.delete('user@example.com')

Audiences (Admin API Key Required)

audience = admin_client.audiences.create(name: 'Newsletter Subscribers', description: 'Main list')

audiences = admin_client.audiences.list(page: 1, limit: 20)

audience = admin_client.audiences.get('aud_abc123')

admin_client.audiences.delete('aud_abc123')

Automations (Admin API Key Required)

automations = admin_client.automations.list

automation = admin_client.automations.get('auto_abc123')

admin_client.automations.enroll('auto_abc123', email: 'user@example.com')

admin_client.automations.unenroll('auto_abc123', email: 'user@example.com')

Domains (Admin API Key Required)

domain = admin_client.domains.add('mail.yourcompany.com')

domains = admin_client.domains.list

status = admin_client.domains.get_status('dom_abc123')

result = admin_client.domains.verify('dom_abc123')

api_key = admin_client.domains.create_api_key(domain_id: 'dom_abc123', name: 'Production Key')

admin_client.domains.delete('dom_abc123')

Error Handling

require 'keplars'

begin
  result = client.emails.send_instant(...)
rescue Keplars::AuthenticationError => e
  puts "Invalid API key: #{e.message}"
rescue Keplars::RateLimitError => e
  puts "Rate limited"
rescue Keplars::ValidationError => e
  puts "Validation error: #{e.message}"
end