Sending Emails with SMTP in Ruby

Send emails through AhaSend’s SMTP servers using Ruby’s versatile email solutions. This guide covers three popular approaches: the built-in net/smtp library, the powerful Mail gem, and Rails’ ActionMailer framework.

Ruby’s Email Flexibility: Ruby offers multiple excellent options for email sending, from lightweight standard library solutions to feature-rich frameworks - choose the one that best fits your application’s needs.

Prerequisites

Before you begin, ensure you have:

System Requirements

Ruby installed on your system (Download Ruby)
Ruby 2.7 or higher (recommended)
Basic knowledge of Ruby programming
Access to install gems (if using Mail gem or Rails)

AhaSend Setup

Domain verified in your AhaSend account
SMTP credentials created (username and password)
Access to your AhaSend dashboard for credential management

Need SMTP Credentials? If you haven’t created SMTP credentials yet, check out our SMTP Credentials guide for step-by-step instructions.

Ruby Email Solutions Overview

Ruby provides multiple excellent options for sending emails via SMTP:

Standard Library

Best for: Simple, lightweight email sending
Pros: No dependencies
Cons: Verbosity
Use case: Scripts

Mail Gem

Best for: non-Rails applications
Pros: High-level API
Cons: Ext. dependency
Use case: Standalone apps

ActionMailer (Rails)

Best for: Rails applications
Pros: Rails integration, templates, testing
Cons: Rails-specific
Use case: Web applications, MVC pattern

Connection Settings

Use these settings for all Ruby SMTP configurations with AhaSend:

Primary Server

Host: send.ahasend.com
Ports: 587 (recommended), 25, 2525
Security: STARTTLS
Authentication: Required

US Server

Host: send-us.ahasend.com
Ports: 587 (recommended), 25, 2525
Security: STARTTLS
Authentication: Required

Method 1: Using net/smtp (Standard Library)

The net/smtp library is part of Ruby’s standard library, offering a lightweight solution for sending emails without external dependencies.

Standard Library Advantage: net/smtp comes with Ruby - no gem installation required! Perfect for simple scripts and lightweight applications.

Basic Examples

require 'net/smtp'

def send_plain_text_email
  # SMTP server configuration
  smtp_settings = {
    address: 'send.ahasend.com',
    port: 587,
    domain: 'yourdomain.com',
    user_name: 'YOUR_SMTP_USERNAME',
    password: 'YOUR_SMTP_PASSWORD',
    authentication: 'plain',
    enable_starttls_auto: true
  }

  # Email content
  from_email = 'hello@yourdomain.com'
  to_email = 'user@example.com'
  subject = 'Welcome to our platform!'
  body = 'Thanks for signing up. We\'re excited to have you!'

  # Construct the email message
  message = <<~MESSAGE_END
    From: Your Company <#{from_email}>
    To: #{to_email}
    Subject: #{subject}
    Date: #{Time.now.rfc2822}
    Content-Type: text/plain; charset=UTF-8

    #{body}
  MESSAGE_END

  # Send the email
  begin
    Net::SMTP.start(
      smtp_settings[:address],
      smtp_settings[:port],
      smtp_settings[:domain],
      smtp_settings[:user_name],
      smtp_settings[:password],
      smtp_settings[:authentication]
    ) do |smtp|
      smtp.enable_starttls
      smtp.send_message(message, from_email, to_email)
    end

    puts "Email sent successfully!"
  rescue => e
    puts "Failed to send email: #{e.message}"
  end
end

# Send the email
send_plain_text_email

require 'net/smtp'

def send_html_email
  # SMTP server configuration
  smtp_settings = {
    address: 'send.ahasend.com',
    port: 587,
    domain: 'yourdomain.com',
    user_name: 'YOUR_SMTP_USERNAME',
    password: 'YOUR_SMTP_PASSWORD',
    authentication: 'plain',
    enable_starttls_auto: true
  }

  # Email content
  from_email = 'hello@yourdomain.com'
  to_email = 'user@example.com'
  subject = 'Welcome to our platform!'

  html_body = <<~HTML
    <html>
    <body>
      <h1>Welcome!</h1>
      <p>Thanks for signing up. We're <strong>excited</strong> to have you!</p>
      <p><a href="https://yourdomain.com/get-started">Get Started</a></p>
    </body>
    </html>
  HTML

  # Construct the email message
  message = <<~MESSAGE_END
    From: Your Company <#{from_email}>
    To: #{to_email}
    Subject: #{subject}
    Date: #{Time.now.rfc2822}
    MIME-Version: 1.0
    Content-Type: text/html; charset=UTF-8

    #{html_body}
  MESSAGE_END

  # Send the email
  begin
    Net::SMTP.start(
      smtp_settings[:address],
      smtp_settings[:port],
      smtp_settings[:domain],
      smtp_settings[:user_name],
      smtp_settings[:password],
      smtp_settings[:authentication]
    ) do |smtp|
      smtp.enable_starttls
      smtp.send_message(message, from_email, to_email)
    end

    puts "HTML email sent successfully!"
  rescue => e
    puts "Failed to send email: #{e.message}"
  end
end

send_html_email

require 'net/smtp'

def send_email_with_headers
  # SMTP server configuration
  smtp_settings = {
    address: 'send.ahasend.com',
    port: 587,
    domain: 'yourdomain.com',
    user_name: 'YOUR_SMTP_USERNAME',
    password: 'YOUR_SMTP_PASSWORD',
    authentication: 'plain',
    enable_starttls_auto: true
  }

  # Email content
  from_email = 'updates@yourdomain.com'
  to_email = 'user@example.com'
  subject = 'Product Updates with Tracking'
  body = 'Check out our latest features at https://yourdomain.com/features'

  # Construct the email message with special headers
  message = <<~MESSAGE_END
    From: Your Company <#{from_email}>
    To: #{to_email}
    Subject: #{subject}
    Date: #{Time.now.rfc2822}
    Content-Type: text/plain; charset=UTF-8
    ahasend-track-opens: true
    ahasend-track-clicks: true
    ahasend-tags: product-update,newsletter,ruby
    ahasend-message-retention: 30
    ahasend-message-data-retention: 7

    #{body}
  MESSAGE_END

  # Send the email
  begin
    Net::SMTP.start(
      smtp_settings[:address],
      smtp_settings[:port],
      smtp_settings[:domain],
      smtp_settings[:user_name],
      smtp_settings[:password],
      smtp_settings[:authentication]
    ) do |smtp|
      smtp.enable_starttls
      smtp.send_message(message, from_email, to_email)
    end

    puts "Email sent with special headers!"
  rescue => e
    puts "Failed to send email: #{e.message}"
  end
end

send_email_with_headers

Method 2: Using the Mail Gem

The Mail gem provides a high-level, Ruby-style interface for email handling with rich features like attachments, multipart messages, and template support.

Mail Gem Benefits: Clean API, automatic MIME handling, built-in attachment support, and excellent template integration. Perfect for complex email applications.

Installation

Add the Mail gem to your project:

# Add to your Gemfile
gem 'mail'

# Then run:
bundle install

gem install mail

Basic Examples

require 'mail'

# Configure Mail gem defaults
Mail.defaults do
  delivery_method :smtp, {
    address: 'send.ahasend.com',
    port: 587,
    user_name: 'YOUR_SMTP_USERNAME',
    password: 'YOUR_SMTP_PASSWORD',
    authentication: 'plain',
    enable_starttls_auto: true
  }
end

def send_plain_text_email
  begin
    mail = Mail.new do
      from     'hello@yourdomain.com'
      to       'user@example.com'
      subject  'Welcome to our platform!'
      body     'Thanks for signing up. We\'re excited to have you!'
    end

    mail.deliver!
    puts "Email sent successfully!"
  rescue => e
    puts "Failed to send email: #{e.message}"
  end
end

send_plain_text_email

require 'mail'

# Configure Mail gem defaults
Mail.defaults do
  delivery_method :smtp, {
    address: 'send.ahasend.com',
    port: 587,
    user_name: 'YOUR_SMTP_USERNAME',
    password: 'YOUR_SMTP_PASSWORD',
    authentication: 'plain',
    enable_starttls_auto: true
  }
end

def send_html_email
  begin
    mail = Mail.new do
      from     'hello@yourdomain.com'
      to       'user@example.com'
      subject  'Welcome to our platform!'

      # Add both text and HTML parts
      text_part do
        body 'Welcome! Thanks for signing up. Visit https://yourdomain.com/get-started to get started.'
      end

      html_part do
        content_type 'text/html; charset=UTF-8'
        body <<~HTML
          <html>
          <body>
            <h1>Welcome!</h1>
            <p>Thanks for signing up. We're <strong>excited</strong> to have you!</p>
            <p><a href="https://yourdomain.com/get-started">Get Started</a></p>
          </body>
          </html>
        HTML
      end
    end

    mail.deliver!
    puts "HTML email sent successfully!"
  rescue => e
    puts "Failed to send email: #{e.message}"
  end
end

send_html_email

require 'mail'

# Configure Mail gem defaults
Mail.defaults do
  delivery_method :smtp, {
    address: 'send.ahasend.com',
    port: 587,
    user_name: 'YOUR_SMTP_USERNAME',
    password: 'YOUR_SMTP_PASSWORD',
    authentication: 'plain',
    enable_starttls_auto: true
  }
end

def send_email_with_attachment
  begin
    mail = Mail.new do
      from     'hello@yourdomain.com'
      to       'user@example.com'
      subject  'Your Invoice is Ready'

      text_part do
        body 'Please find your invoice attached to this email.'
      end

      html_part do
        content_type 'text/html; charset=UTF-8'
        body <<~HTML
          <html>
          <body>
            <h1>Invoice Attached</h1>
            <p>Please find your invoice attached to this email.</p>
          </body>
          </html>
        HTML
      end

      # Add attachment
      add_file '/path/to/invoice.pdf'
    end

    mail.deliver!
    puts "Email with attachment sent successfully!"
  rescue => e
    puts "Failed to send email: #{e.message}"
  end
end

send_email_with_attachment

Advanced Mail Gem Features

require 'mail'

# Configure Mail gem defaults
Mail.defaults do
  delivery_method :smtp, {
    address: 'send.ahasend.com',
    port: 587,
    user_name: 'YOUR_SMTP_USERNAME',
    password: 'YOUR_SMTP_PASSWORD',
    authentication: 'plain',
    enable_starttls_auto: true
  }
end

def send_email_with_special_headers
  begin
    mail = Mail.new do
      from     'updates@yourdomain.com'
      to       ['user1@example.com', 'user2@example.com']
      cc       'manager@yourdomain.com'
      bcc      'analytics@yourdomain.com'
      subject  'Product Updates with Tracking'

      # Add AhaSend special headers
      header['ahasend-track-opens'] = 'true'
      header['ahasend-track-clicks'] = 'true'
      header['ahasend-tags'] = 'product-update,newsletter,ruby'
      header['ahasend-message-retention'] = '30'
      header['ahasend-message-data-retention'] = '7'

      text_part do
        body 'Check out our latest features at https://yourdomain.com/features'
      end

      html_part do
        content_type 'text/html; charset=UTF-8'
        body <<~HTML
          <html>
          <body>
            <h1>Product Updates</h1>
            <p>Check out our <a href="https://yourdomain.com/features">latest features</a>!</p>
            <p>This email has tracking enabled and custom tags.</p>
          </body>
          </html>
        HTML
      end
    end

    mail.deliver!
    puts "Email sent with special headers!"
  rescue => e
    puts "Failed to send email: #{e.message}"
  end
end

send_email_with_special_headers

require 'mail'

# Configure Mail gem defaults
Mail.defaults do
  delivery_method :smtp, {
    address: 'send.ahasend.com',
    port: 587,
    user_name: 'YOUR_SMTP_USERNAME',
    password: 'YOUR_SMTP_PASSWORD',
    authentication: 'plain',
    enable_starttls_auto: true
  }
end

def send_bulk_emails_with_templates
  # Recipients list
  recipients = [
    { email: 'user1@example.com', name: 'John Doe', plan: 'Premium' },
    { email: 'user2@example.com', name: 'Jane Smith', plan: 'Basic' },
    { email: 'user3@example.com', name: 'Bob Johnson', plan: 'Pro' }
  ]

  recipients.each do |recipient|
    begin
      mail = Mail.new do
        from     'hello@yourdomain.com'
        to       recipient[:email]
        subject  'Personalized Newsletter'

        # Add custom headers
        header['ahasend-tags'] = 'newsletter,bulk,ruby'

        text_part do
          body "Hello #{recipient[:name]}! Your #{recipient[:plan]} plan gives you amazing benefits."
        end

        html_part do
          content_type 'text/html; charset=UTF-8'
          body <<~HTML
            <html>
            <body>
              <h1>Hello #{recipient[:name]}!</h1>
              <p>Your <strong>#{recipient[:plan]}</strong> plan gives you amazing benefits.</p>
              <p>This is your personalized newsletter.</p>
            </body>
            </html>
          HTML
        end
      end

      mail.deliver!
      puts "Email sent to #{recipient[:email]}"

      # Add delay to avoid rate limiting
      sleep(0.1)
    rescue => e
      puts "Failed to send to #{recipient[:email]}: #{e.message}"
    end
  end

  puts "Bulk email sending completed!"
end

send_bulk_emails_with_templates

require 'mail'

class EmailService
  def initialize(smtp_config = {})
    default_config = {
      address: 'send.ahasend.com',
      port: 587,
      user_name: ENV['SMTP_USERNAME'],
      password: ENV['SMTP_PASSWORD'],
      authentication: 'plain',
      enable_starttls_auto: true
    }

    @smtp_config = default_config.merge(smtp_config)
    configure_mail!
  end

  def send_welcome_email(to:, name:)
    send_email(
      to: to,
      subject: 'Welcome to our platform!',
      template: :welcome,
      data: { name: name }
    )
  end

  def send_notification(to:, title:, message:, tags: [])
    send_email(
      to: to,
      subject: title,
      template: :notification,
      data: { title: title, message: message },
      headers: { 'ahasend-tags' => tags.join(',') }
    )
  end

  private

  def configure_mail!
    Mail.defaults do
      delivery_method :smtp, @smtp_config
    end
  end

  def send_email(to:, subject:, template:, data:, headers: {})
    begin
      mail = Mail.new do
        from     'hello@yourdomain.com'
        to       to
        subject  subject

        # Add custom headers
        headers.each { |key, value| header[key] = value }

        text_part do
          body generate_text_template(template, data)
        end

        html_part do
          content_type 'text/html; charset=UTF-8'
          body generate_html_template(template, data)
        end
      end

      mail.deliver!
      true
    rescue => e
      puts "Failed to send email: #{e.message}"
      false
    end
  end

  def generate_text_template(template, data)
    case template
    when :welcome
      "Hello #{data[:name]}! Welcome to our platform. We're excited to have you!"
    when :notification
      "#{data[:title]}\n\n#{data[:message]}"
    else
      "Email content"
    end
  end

  def generate_html_template(template, data)
    case template
    when :welcome
      <<~HTML
        <html><body>
          <h1>Hello #{data[:name]}!</h1>
          <p>Welcome to our platform. We're <strong>excited</strong> to have you!</p>
        </body></html>
      HTML
    when :notification
      <<~HTML
        <html><body>
          <h1>#{data[:title]}</h1>
          <p>#{data[:message]}</p>
        </body></html>
      HTML
    else
      "<html><body><p>Email content</p></body></html>"
    end
  end
end

# Usage example
email_service = EmailService.new

# Send welcome email
success = email_service.send_welcome_email(
  to: 'user@example.com',
  name: 'John Doe'
)

# Send notification
email_service.send_notification(
  to: 'user@example.com',
  title: 'Account Update',
  message: 'Your account has been successfully updated.',
  tags: ['notification', 'account', 'ruby']
)

Method 3: Using ActionMailer (Rails)

ActionMailer is part of Ruby on Rails and provides a comprehensive email solution with MVC patterns, templates, and excellent testing support.

Rails Integration: ActionMailer seamlessly integrates with Rails applications, providing view templates, internationalization, background job support, and comprehensive testing utilities.

Configuration

Configure your SMTP settings in the appropriate environment file:

# Production environment configuration
Rails.application.configure do
  # Email configuration
  config.action_mailer.delivery_method = :smtp
  config.action_mailer.smtp_settings = {
    address: 'send.ahasend.com',
    port: 587,
    domain: 'yourdomain.com',
    user_name: ENV['SMTP_USERNAME'],
    password: ENV['SMTP_PASSWORD'],
    authentication: 'plain',
    enable_starttls_auto: true
  }

  # Set default host for URL generation
  config.action_mailer.default_url_options = {
    host: 'yourdomain.com',
    protocol: 'https'
  }
end

# Development environment configuration
Rails.application.configure do
  # Email configuration for development
  config.action_mailer.delivery_method = :smtp
  config.action_mailer.smtp_settings = {
    address: 'send.ahasend.com',
    port: 587,
    domain: 'yourdomain.com',
    user_name: ENV['SMTP_USERNAME'],
    password: ENV['SMTP_PASSWORD'],
    authentication: 'plain',
    enable_starttls_auto: true
  }

  # For development, you might want to use sandbox mode
  config.action_mailer.default_url_options = {
    host: 'localhost:3000',
    protocol: 'http'
  }
end

# Add to your .env file
SMTP_USERNAME=your_smtp_username
SMTP_PASSWORD=your_smtp_password

Basic Mailer Setup

class UserMailer < ActionMailer::Base
  default from: 'hello@yourdomain.com'

  def welcome_email(user)
    @user = user
    @url = root_url

    mail(
      to: user.email,
      subject: 'Welcome to our platform!'
    )
  end

  def notification_email(user, title, message)
    @user = user
    @title = title
    @message = message

    # Add AhaSend special headers
    headers['ahasend-track-opens'] = 'true'
    headers['ahasend-track-clicks'] = 'true'
    headers['ahasend-tags'] = 'notification,rails'

    mail(
      to: user.email,
      subject: title
    )
  end
end

<!DOCTYPE html>
<html>
<head>
  <meta content='text/html; charset=UTF-8' http-equiv='Content-Type' />
  <style>
    body { font-family: Arial, sans-serif; line-height: 1.6; }
    .container { max-width: 600px; margin: 0 auto; padding: 20px; }
    .header { background-color: #f8f9fa; padding: 20px; text-align: center; }
    .content { padding: 20px; }
    .button {
      display: inline-block;
      padding: 12px 24px;
      background-color: #007bff;
      color: white;
      text-decoration: none;
      border-radius: 4px;
    }
  </style>
</head>
<body>
  <div class="container">
    <div class="header">
      <h1>Welcome to Our Platform!</h1>
    </div>
    <div class="content">
      <p>Hello <%= @user.name %>,</p>

      <p>Thanks for signing up! We're excited to have you on board.</p>

      <p><%= link_to "Get Started", @url, class: "button" %></p>

      <p>Best regards,<br>The Team</p>
    </div>
  </div>
</body>
</html>

class UsersController < ApplicationController
  def create
    @user = User.new(user_params)

    if @user.save
      # Send welcome email asynchronously
      UserMailer.welcome_email(@user).deliver_later

      redirect_to @user, notice: 'User created successfully!'
    else
      render :new
    end
  end
end

Testing with Sandbox Mode

Use sandbox mode to safely test your Ruby email integration across all methods:

require 'net/smtp'

def send_sandbox_test
  smtp_settings = {
    address: 'send.ahasend.com',
    port: 587,
    domain: 'yourdomain.com',
    user_name: 'YOUR_SMTP_USERNAME',
    password: 'YOUR_SMTP_PASSWORD',
    authentication: 'plain'
  }

  message = <<~MESSAGE_END
    From: test@yourdomain.com
    To: test@example.com
    Subject: Sandbox Test Email
    AhaSend-Sandbox: true
    AhaSend-Sandbox-Result: deliver

    This email is sent in sandbox mode for testing.
  MESSAGE_END

  begin
    Net::SMTP.start(
      smtp_settings[:address], smtp_settings[:port], smtp_settings[:domain],
      smtp_settings[:user_name], smtp_settings[:password], smtp_settings[:authentication]
    ) do |smtp|
      smtp.enable_starttls
      smtp.send_message(message, 'test@yourdomain.com', 'test@example.com')
    end

    puts "Sandbox email sent successfully!"
  rescue => e
    puts "Failed to send sandbox email: #{e.message}"
  end
end

send_sandbox_test

require 'mail'

Mail.defaults do
  delivery_method :smtp, {
    address: 'send.ahasend.com',
    port: 587,
    user_name: 'YOUR_SMTP_USERNAME',
    password: 'YOUR_SMTP_PASSWORD',
    authentication: 'plain',
    enable_starttls_auto: true
  }
end

def send_sandbox_bounce_test
  begin
    mail = Mail.new do
      from     'test@yourdomain.com'
      to       'test@example.com'
      subject  'Sandbox Bounce Test'

      # Enable sandbox mode with bounce simulation
      header['AhaSend-Sandbox'] = 'true'
      header['AhaSend-Sandbox-Result'] = 'bounce'

      body 'This email simulates a bounce for webhook testing.'
    end

    mail.deliver!
    puts "Sandbox bounce test sent - check webhooks!"
  rescue => e
    puts "Failed to send sandbox email: #{e.message}"
  end
end

send_sandbox_bounce_test

# app/mailers/test_mailer.rb
class TestMailer < ApplicationMailer
  def sandbox_test(email, result_type = 'deliver')
    headers['AhaSend-Sandbox'] = 'true'
    headers['AhaSend-Sandbox-Result'] = result_type

    mail(
      to: email,
      subject: "Sandbox Test - #{result_type.capitalize}",
      body: "This is a sandbox test email simulating: #{result_type}"
    )
  end
end

# Usage in Rails console or controller
TestMailer.sandbox_test('test@example.com', 'deliver').deliver_now
TestMailer.sandbox_test('test@example.com', 'bounce').deliver_now
TestMailer.sandbox_test('test@example.com', 'reject').deliver_now

Sandbox Benefits: Emails sent in sandbox mode are free, trigger webhooks normally, and never actually deliver to recipients - perfect for development and testing.

Resources

Ruby net/smtp Documentation

Official net/smtp library documentation

Mail Gem Documentation

Comprehensive Mail gem guide and examples

ActionMailer Guide

Official Rails ActionMailer documentation

AhaSend Support

Get help from our engineering team

Getting Started

Sending with SMTP

Sending with the API

Email Tracking

Integrations

Data Retention

Security

Scaling up

Sending emails in Ruby

Sending Emails with SMTP in Ruby

Prerequisites

Ruby Email Solutions Overview

Standard Library

Mail Gem

ActionMailer (Rails)

Connection Settings

Primary Server

US Server

Method 1: Using net/smtp (Standard Library)

Basic Examples

Method 2: Using the Mail Gem

Installation

Basic Examples

Advanced Mail Gem Features

Method 3: Using ActionMailer (Rails)

Configuration

Basic Mailer Setup

Testing with Sandbox Mode

Resources

Ruby net/smtp Documentation

Mail Gem Documentation

ActionMailer Guide

AhaSend Support

​Sending Emails with SMTP in Ruby

​Prerequisites

​Ruby Email Solutions Overview

Standard Library

Mail Gem

ActionMailer (Rails)

​Connection Settings

Primary Server

US Server

​Method 1: Using net/smtp (Standard Library)

​Basic Examples

​Method 2: Using the Mail Gem

​Installation

​Basic Examples

​Advanced Mail Gem Features

​Method 3: Using ActionMailer (Rails)

​Configuration

​Basic Mailer Setup

​Testing with Sandbox Mode

​Resources

Ruby net/smtp Documentation

Mail Gem Documentation

ActionMailer Guide

AhaSend Support

Sending Emails with SMTP in Ruby

Prerequisites

Ruby Email Solutions Overview

Connection Settings

Method 1: Using net/smtp (Standard Library)

Basic Examples

Method 2: Using the Mail Gem

Installation

Basic Examples

Advanced Mail Gem Features

Method 3: Using ActionMailer (Rails)

Configuration

Basic Mailer Setup

Testing with Sandbox Mode

Resources