Ruby SDK

The HiSend Ruby SDK (hisend) provides a convenient wrapper around our REST APIs. It is built entirely on Ruby's standard library (Net::HTTP and JSON), which means it has zero runtime dependencies. This makes it incredibly fast, lightweight, and completely immune to dependency conflicts.

Installation

You can install the SDK using gem:

gem install hisend

Or add it to your Gemfile:

gem 'hisend'

Initialization

Import the client and initialize it using the API Key generated in your project dashboard.

require 'hisend'

client = Hisend::Client.new(api_key: 'YOUR_API_KEY')

# You can optionally pass `base_url:` if using a custom endpoint gateway
# client = Hisend::Client.new(api_key: 'YOUR_API_KEY', base_url: 'https://api.hisend.app/v1')

Resources

The SDK is divided into resources, each handling a specific domain of the API. These are accessible via the initialized client. For modifying API structures, we rely on standard Ruby Hashes which are automatically converted to JSON.

Emails (client.emails)

The emails resource handles sending messages and fetching sent/received history.

send(data)

Sends a single email.

result = client.emails.send({
  from: 'noreply@yourdomain.com',
  to: ['user@example.com'],
  # Optional fields:
  cc: ['team@yourdomain.com'],
  bcc: ['hidden@yourdomain.com'],
  subject: 'Welcome to HiSend!',
  html: '<h1>Welcome!</h1><p>We are glad to have you.</p>',
  text: 'Welcome! We are glad to have you.',
})

send_batch(data)

Sends multiple emails in a single API request, useful for bulk messaging/newsletters.

batch = [
  { from: 'sales@test.com', to: ['a@test.com'] },
  { from: 'sales@test.com', to: ['b@test.com'] },
]

result = client.emails.send_batch(batch)

list()

Returns a list of all emails (inbound and outbound) belonging to your project.

emails = client.emails.list
puts "You have #{emails.length} emails."

get(id)

Retrieves the details of a specific email by its ID.

email = client.emails.get(1234)
puts email[:subject]

Threads (client.threads)

The threads resource handles email conversations, grouping inbound and outbound replies into manageable topics.

list()

Returns all conversation threads for your project, ordered by the latest message time.

threads = client.threads.list

get_emails(id)

Returns all individual emails that belong to a specific Thread ID, in chronological order.

emails_in_thread = client.threads.get_emails(849)
emails_in_thread.each do |msg|
  puts "#{msg[:from]}: #{msg[:text_body]}"
end

Domains (client.domains)

The domains resource manages the sender domains authorized for your project.

list()

Returns all domains registered to your project along with their verification statuses.

domains = client.domains.list

get(id)

Retrieves the details and verification status of a specific domain by its ID.

domain = client.domains.get(101)

add(data)

Registers a new domain to your project. Note that it will remain pending until you verify its DNS records.

domain = client.domains.add({
  name: 'newsletter.example.com'
})

verify(id)

Triggers a manual DNS check to verify if the required records (MX, TXT, CNAME) have been added to your registrar.

result = client.domains.verify(domain[:id])
puts "Verification status: #{result[:verification_status]}"

delete(id)

Removes a domain from your project.

client.domains.delete(domain[:id])

Routing (client.routing)

The routing resource manages how inbound emails are processed, allowing for Catch-All or exact-address routing.

list(domain_id)

Returns all inbound email routing rules configured for a specific domain.

routes = client.routing.list(domain_id)

get(domain_id, id)

Returns the details of a specific routing rule.

route = client.routing.get(domain_id, route_id)

create(domain_id, data)

Creates a new routing rule on a specific domain.

rule = client.routing.create(domain_id, {
  type: 'specific_address',
  email_address: 'support@yourdomain.com',
  endpoint_ids: [102, 103]
})

update(domain_id, id, data)

Updates an existing routing rule on a specific domain.

updated_rule = client.routing.update(domain_id, rule[:id], {
  endpoint_ids: [102]
})

delete(domain_id, id)

Deletes an existing inbound routing rule.

client.routing.delete(domain_id, rule[:id])

Error Handling

All methods in the SDK will raise a Hisend::Error exception if the API request is rejected (e.g., HTTP 401 Unauthorized or HTTP 400 Bad Request). The exception parses the error message safely and also gives you access to the HTTP status code.

begin
  result = client.emails.send(req)
rescue Hisend::Error => e
  puts "Failed to send email: #{e.message} (Status: #{e.status_code})"
end