Ruby

Installation

Install the gem

gem 'keplars'

Then run:

bundle install

gem install keplars

Set your API key

KEPLARS_API_KEY=kms_your_workspace_id.live_your_secret

Send your first email

require 'keplars'

client = Keplars::Client.new(api_key: ENV['KEPLARS_API_KEY'])

response = client.emails.send_instant(
  from:    '[email protected]',
  to:      '[email protected]',
  subject: 'Hello!',
  body:    '<h1>It works!</h1>',
  is_html: true
)

puts response[:id]

Priority Levels

Method	Delivery	Use case
`send_instant`	0–5 seconds	OTP, 2FA, password reset
`send_high`	0–30 seconds	Transactional confirmations
`send_async` / `send`	0–5 minutes	Welcome emails, notifications
`send_bulk`	Background	Newsletters, campaigns

client.emails.send_instant(...)
client.emails.send_high(...)
client.emails.send_async(...)
client.emails.send_bulk(...)

Using Templates

response = client.emails.send_instant(
  from:        '[email protected]',
  to:          '[email protected]',
  template_id: 'your-template-id',
  params: {
    user_name:         'Jane',
    verification_code: '123456'
  }
)

Schedule an Email

response = client.emails.schedule(
  from:          '[email protected]',
  to:            '[email protected]',
  subject:       'Weekly digest',
  body:          '<p>Here is your digest.</p>',
  is_html:       true,
  scheduled_for: '2026-02-01T09:00:00Z',
  timezone:      'America/New_York'
)

Error Handling

begin
  response = client.emails.send_instant(...)
rescue Keplars::AuthenticationError
  puts 'Invalid API key'
rescue Keplars::RateLimitError => e
  puts "Rate limit hit, retry after: #{e.retry_after}"
rescue Keplars::ValidationError => e
  puts "Validation error: #{e.message}"
end

Admin API

Need to manage contacts, audiences, automations, or domains? Use an admin key - same client, different key suffix:

client = Keplars::Client.new(api_key: 'kms_xxx.adm_xxx')

client.contacts.add(email: '[email protected]', name: 'Jane')
client.audiences.create('Newsletter')
client.automations.enroll('auto_id', '[email protected]')
client.domains.verify('domain_id')

See the full Admin API reference.

Next Steps

Admin API - Contacts, audiences, automations, domains
Send Emails - API reference
Email Templates - Build reusable templates
Schedule Emails - Delayed delivery

Ruby

On this page