Rails Action Mailer SMTP Settings

Before you start

Tick off what you already have. New to tinyRelay? See how onboarding works.

0 of 4 in placeTap each one you already have.

A tinyRelay accountSet up by our team during onboarding.SMTP credentialsA username and password, plus the [SMTP host], [port] and [encryption] to use, all issued at onboarding.A DKIM-signed sender domainSet up with tinyRelay, with the CNAME tec1._domainkey.yourdomain.com pointing to tec1.dkim.tinyemail.com.A Rails app with Action MailerAnd an Active Job backend if you use deliver_later.

SMTP host, port and encryption are issued at onboarding. This guide shows them as [SMTP host], [port] and [encryption]. Whether SMTP sends receive the same webhooks and metadata as API sends is being confirmed.

Configure Rails Action Mailer SMTP

Action Mailer reads its SMTP connection from the environment config. Keep the username and password in Rails credentials.

1. Store the SMTP credentials

Credentials

credentials.yml.enc Environment

Copy

# bin/rails credentials:edit
tinyrelay:
  smtp_user_name: "[SMTP username]"
  smtp_password: "[SMTP password]"

export TINYRELAY_SMTP_HOST="[SMTP host]"
export TINYRELAY_SMTP_PORT="[port]"

2. Fill smtp_settings

Use enable_starttls: true for STARTTLS, or tls: true for implicit TLS. Match the [encryption] you were given.

config/environments/production.rb

STARTTLS Implicit TLS

Copy

# config/environments/production.rb
config.action_mailer.delivery_method = :smtp
config.action_mailer.smtp_settings = {
  address:         ENV.fetch("TINYRELAY_SMTP_HOST"),           # [SMTP host]
  port:            Integer(ENV.fetch("TINYRELAY_SMTP_PORT")),  # [port]
  user_name:       Rails.application.credentials.dig(:tinyrelay, :smtp_user_name),
  password:        Rails.application.credentials.dig(:tinyrelay, :smtp_password),
  authentication:  :plain,      # [auth method]: confirm at onboarding
  enable_starttls: true,        # [encryption] is STARTTLS
  open_timeout:    5,
  read_timeout:    5
}
config.action_mailer.default_url_options = { host: "acme.com", protocol: "https" }

# config/environments/production.rb
config.action_mailer.delivery_method = :smtp
config.action_mailer.smtp_settings = {
  address:        ENV.fetch("TINYRELAY_SMTP_HOST"),           # [SMTP host]
  port:           Integer(ENV.fetch("TINYRELAY_SMTP_PORT")),  # [port]
  user_name:      Rails.application.credentials.dig(:tinyrelay, :smtp_user_name),
  password:       Rails.application.credentials.dig(:tinyrelay, :smtp_password),
  authentication: :plain,       # [auth method]: confirm at onboarding
  tls:            true,         # [encryption] is implicit TLS
  open_timeout:   5,
  read_timeout:   5
}
config.action_mailer.default_url_options = { host: "acme.com", protocol: "https" }

3. Set a default from address

app/mailers/application_mailer.rbCopy

# app/mailers/application_mailer.rb
class ApplicationMailer < ActionMailer::Base
  default from: email_address_with_name("no-reply@acme.com", "Acme")
  layout "mailer"
end

4. Send a test email

app/mailers/smtp_test_mailer.rbCopy

# app/mailers/smtp_test_mailer.rb
class SmtpTestMailer < ApplicationMailer
  def ping(to)
    mail(to: to, subject: "tinyRelay SMTP test", body: "It works.")
  end
end

# Then, in the environment you configured:
# RAILS_ENV=production bin/rails runner 'SmtpTestMailer.ping("you@example.com").deliver_now'

Send Rails email with deliver_later

Your existing mailers work unchanged. Enqueue them with deliver_later so a slow SMTP handshake never holds up a page load.

app/mailers/user_mailer.rbCopy

# app/mailers/user_mailer.rb
class UserMailer < ApplicationMailer
  def password_reset
    @user = params[:user]
    @token = params[:token]
    mail(to: email_address_with_name(@user.email, @user.name),
         subject: "Reset your Acme password")
  end
end

# Enqueue with Active Job, so the request does not wait on SMTP
UserMailer.with(user: user, token: token).password_reset.deliver_later

Need per-recipient metadata?

Action Mailer sends over SMTP. For one request to many recipients, each with their own IDs echoed on webhooks, use the REST API from Ruby: see send email with Ruby.

Delivery events and the REST API

Documented

REST API sends

tinyRelay posts signed webhook events (SEND, DELIVERED, BOUNCED, OPEN, CLICK, UNSUBSCRIBE and SPAM) with your metadata on each one.

Being confirmed

SMTP sends

Whether SMTP sends receive the same webhooks and metadata is being confirmed, and this guide will be updated when it is.

If you need your own IDs echoed on every event today, send those messages through the API instead: see the transactional email API and email webhooks.

Troubleshooting

What do you see?5 common symptoms

Authentication failed Connection timed out or refused TLS or SSL handshake error Sender address rejected Accepted but never arrives

Authentication failedWhat to check

The username or password does not match what was issued at onboarding. Copy them again and check for stray quotes or spaces in your environment file.

Connection timed out or refusedWhat to check

Check [SMTP host] and [port]. Some hosting providers block outbound SMTP ports; ask yours if a correct host and port still time out.

TLS or SSL handshake errorWhat to check

The encryption mode does not match the port. STARTTLS and implicit TLS are different settings; use the [encryption] you were given.

Sender address rejectedWhat to check

Send from an address on a domain that was set up with tinyRelay during onboarding.

Accepted but never arrivesWhat to check

Check the DKIM CNAME on your sender domain, then the recipient address. The email bounce codes reference explains each bounce category.

FAQ

What SMTP host and port should Rails use for tinyRelay?

The values issued at onboarding with your SMTP credentials. They are not published, so this guide shows them as placeholders.

Should I use enable_starttls or tls?

Use enable_starttls: true when the encryption you were issued is STARTTLS, and tls: true when it is implicit TLS. Do not set both.

Where should the SMTP password live in Rails?

In Rails credentials or an environment variable, read in the environment config. Never commit it in plain text.

Do Rails emails sent over SMTP get tinyRelay webhooks?

This is being confirmed. Email sent through the REST API gets signed webhook events with your metadata; this guide will be updated for SMTP.

Next steps

Sources

Ruby on Rails Guides: Action Mailer Basics

Rails Action Mailer SMTP settings

Before you start

Configure Rails Action Mailer SMTP

1. Store the SMTP credentials

2. Fill smtp_settings

3. Set a default from address

4. Send a test email

Send Rails email with deliver_later

Need per-recipient metadata?

Delivery events and the REST API

Troubleshooting

FAQ

Next steps

Sources

Send transactional email with a service that reports back.