Send emails with Ruby

In this quickstart, you'll learn how to send transactional emails from your Ruby app with Sidemail. You'll set up the SDK, send your first email, and see examples for common use cases like welcome emails, password resets, and scheduled reports.

Before you start

  1. Create a Sidemail account → get your API key
  2. Add a sending domain → set up your domain for sending

1. Install

gem install sidemail

2. Add your API key

Add your Sidemail API key to your environment variables (e.g. in .env if you use dotenv):

SIDEMAIL_API_KEY=your-api-key

3. Setup

Initialize the client. The SDK automatically reads SIDEMAIL_API_KEY from your environment variables if you don't provide it explicitly.

Option A: Simple setup

Use this for simple scripts.

require "sidemail"

# Reads SIDEMAIL_API_KEY from environment variables automatically
# or pass api_key: "your-key"
sm = Sidemail.new

Option B: Shared instance

For larger applications, create a sidemail_client.rb file that exports the configured instance.

# sidemail_client.rb
require "sidemail"

$sidemail = Sidemail.new

4. Send a welcome email

require "sidemail"

sm = Sidemail.new

sm.send_email(
  toAddress: "[email protected]",
  fromAddress: "[email protected]",
  fromName: "Your App",
  templateName: "Welcome",
  templateProps: { firstName: "Alex" }
)

5. Send a password reset email

sm.send_email(
  toAddress: "[email protected]",
  fromAddress: "[email protected]",
  fromName: "Your App",
  templateName: "Password Reset",
  templateProps: {
    actionUrl: "https://myapp.com/reset/token123"
  }
)

6. Send a weekly report (Script)

Create a standalone script to run via cron.

# scripts/send_weekly_report.rb
require "sidemail"

sm = Sidemail.new

# In a real app, fetch this from your database
new_signups = 150
chart_data = [100, 200, 300, 400, 200, 300, 200, 500]

sm.send_email(
  toAddress: "[email protected]",
  fromAddress: "[email protected]",
  fromName: "My App",
  templateName: "Weekly Report",
  templateProps: {
    signups: new_signups,
    chart: chart_data
  }
)

puts "Weekly report sent"

7. Send HTML email

html_content = "<html><body><h1>Hello world! 👋</h1></body></html>"

sm.send_email(
  toAddress: "[email protected]",
  fromAddress: "[email protected]",
  fromName: "Your App",
  subject: "Testing HTML email",
  html: html_content
)

8. Send Markdown email

Store your markdown content in a file and load it (learn more).

markdown_content = File.read("templates/welcome.md")

# Subject and sender are defined in the markdown frontmatter
sm.send_email(
  toAddress: "[email protected]",
  markdown: markdown_content,
  templateProps: {
    name: "John",
    link: "https://example.com"
  }
)

9. Send plain text email

sm.send_email(
  toAddress: "[email protected]",
  fromAddress: "[email protected]",
  fromName: "Your App",
  subject: "Hello",
  text: "Hello! 👋"
)

10. Schedule email

Send email later. Set scheduledAt to an ISO date string.

require "date"

# Schedule for 1 hour from now
scheduled_at = (Time.now + 60 * 60).utc.iso8601

sm.send_email(
  toAddress: "[email protected]",
  fromAddress: "[email protected]",
  fromName: "Your App",
  templateName: "Welcome",
  templateProps: { firstName: "Alex" },
  scheduledAt: scheduled_at
)

11. Send with attachment

Use the Sidemail.file_to_attachment helper to attach files.

file_content = File.read("invoice.pdf")
attachment = Sidemail.file_to_attachment("invoice.pdf", file_content)

sm.send_email(
  toAddress: "[email protected]",
  fromAddress: "[email protected]",
  fromName: "Your App",
  subject: "Your invoice",
  text: "See attached.",
  attachments: [attachment]
)

12. Handle errors

begin
  sm.send_email(
    # ...
  )
rescue Sidemail::Error => e
  puts "Sidemail error: #{e.message}"
  puts "Status: #{e.http_status}" if e.http_status
  puts "Code: #{e.error_code}" if e.error_code
end