Elastic Email Ruby SDK

The official Ruby client library for the Elastic Email REST API v4.

Installation • Quick start • Examples • API reference • Models • Contributing

• Transactional and bulk email. Send single messages, bulk campaigns or CSV merge-file sends.
• Contacts, lists and segments. Add, update, import, export and bulk-delete contacts.
• Campaigns and automations. Create, update, pause and trigger automations for a contact.
• Templates, files and attachments. Manage templates and uploaded files.
• Domains. Verify sending domains and check SPF, DKIM, tracking and certificate status.
• Webhooks and inbound routes. Receive delivery events and route incoming mail.
• Statistics, events and suppressions. Track delivery, bounces, complaints and unsubscribes.
• Subaccounts and security. Manage subaccounts and API keys.
• Plain Ruby objects. Models are built from keyword hashes with snake_case keys, and every call has a …_with_http_info variant that also returns the status code and headers.

You'll also need an Elastic Email API key. You can create one in your API settings. Each endpoint's documentation lists the access level it needs.

Install the ElasticEmail gem from RubyGems:

gem install ElasticEmail

Or add it to your Gemfile:

gem 'ElasticEmail', '~> 4.2'

and run bundle install. RubyGems installs the dependency (Typhoeus) for you.

require 'ElasticEmail'

ElasticEmail.configure do |config|
  config.api_key['X-ElasticEmail-ApiKey'] = ENV.fetch('ELASTICEMAIL_API_KEY')
end

emails = ElasticEmail::EmailsApi.new

message = ElasticEmail::EmailTransactionalMessageData.new(
  recipients: ElasticEmail::TransactionalRecipient.new(to: ['john.doe@example.com']),
  content: ElasticEmail::EmailContent.new(
    from: 'My App <no-reply@yourdomain.com>',
    subject: 'Welcome aboard!',
    body: [
      ElasticEmail::BodyPart.new(content_type: ElasticEmail::BodyContentType::HTML, content: '<h1>Hello!</h1><p>Thanks for signing up.</p>'),
      ElasticEmail::BodyPart.new(content_type: ElasticEmail::BodyContentType::PLAIN_TEXT, content: 'Hello! Thanks for signing up.')
    ]
  )
)

begin
  result = emails.emails_transactional_post(message)
  puts "Sent. TransactionID: #{result.transaction_id}, MessageID: #{result.message_id}"
rescue ElasticEmail::ApiError => e
  puts "Elastic Email API error #{e.code}: #{e.response_body}"
end

The from address must use a domain you've verified in your Elastic Email account.

message = ElasticEmail::EmailTransactionalMessageData.new(
  recipients: ElasticEmail::TransactionalRecipient.new(to: ['john.doe@example.com']),
  content: ElasticEmail::EmailContent.new(
    from: 'My App <no-reply@yourdomain.com>',
    template_name: 'welcome-template',
    merge: { 'firstname' => 'John' }
  )
)

emails.emails_transactional_post(message)

ElasticEmail.configure do |config|
  config.timeout = 30          # seconds; 0 (default) means no timeout
  config.debugging = true      # log requests and responses to config.logger
  config.ssl_ca_cert = '/path/to/ca-bundle.crt'
end

More complete, runnable samples are in the Elastic Email examples repository. It covers transactional email, SMTP, webhooks, inbound email, contacts and serverless platforms across 20+ languages and frameworks.

• 💎 Ruby examples
• 📂 All examples

• Up to 20 concurrent connections per account
• A hard timeout of 600 seconds per request

All URIs are relative to https://api.elasticemail.com/v4. The SDK covers 114 endpoints across 16 API classes: CampaignsApi, ContactsApi, DomainsApi, EmailsApi, EventsApi, FilesApi, InboundRouteApi, ListsApi, SecurityApi, SegmentsApi, StatisticsApi, SubAccountsApi, SuppressionsApi, TemplatesApi, VerificationsApi and WebhookApi, all in the ElasticEmail module.

The spec/ folder has generated RSpec specs for every API class and model:

bundle install
bundle exec rspec

The SDK follows the Elastic Email API v4. Package versions and release notes are listed on RubyGems and in GitHub Releases.

Contributions are welcome! Most of this SDK is generated from the Elastic Email OpenAPI specification, so please read CONTRIBUTING.md before opening a pull request.

• 🐛 Report a bug
• 💡 Request a feature
• 🔒 Report a security issue

This project follows the Contributor Covenant Code of Conduct.

• 💬 Chat with support on elasticemail.com (preferred)
• 📚 API documentation
• 🧪 Examples repository
• 🐛 GitHub issues, for bugs in this SDK only

Released under the MIT License. Copyright © 2021–2026 Elastic Email.