Skip to content

Ruby on Rails

Guide for applications built with Ruby on Rails 7.x / 8.x. Mailexam connects via Action Mailer and SMTP settings in config.

What you need

  • A Mailexam account and a project with SMTP credentials.
  • Ruby 3.2+ and a Rails application (rails new).

Copy from the welcome email (or dashboard) for your project:

  • YOUR_LOGIN — SMTP login (for example, xxxxx);
  • YOUR_PASSWORD — SMTP password (a unique pair with the login);
  • host — YOUR_LOGIN.mailexam.io (matches the login).

1. Dependencies

In Gemfile to load .env in development:

gem "dotenv-rails", groups: %i[development test]

bundle install

2. Environment variables

.env file in the project root (add to .gitignore):

MAILEXAM_LOGIN=YOUR_LOGIN
MAILEXAM_PASSWORD=YOUR_PASSWORD
MAILEXAM_PORT=587
MAIL_FROM=noreply@example.test

SMTP host: YOUR_LOGIN.mailexam.io.

Sender address

MAIL_FROM can be any test address — the message goes to Mailexam, not to a real recipient.

Alternative ports

MAILEXAM_PORT=587

enable_starttls_auto: true

MAILEXAM_PORT=2525

STARTTLS, same as for 587.

MAILEXAM_PORT=25

enable_starttls_auto: false

3. Action Mailer configuration

config/environments/development.rb (similarly for production via environment variables on the server):

login = ENV.fetch("MAILEXAM_LOGIN")
port = ENV.fetch("MAILEXAM_PORT", "587").to_i

config.action_mailer.delivery_method = :smtp
config.action_mailer.raise_delivery_errors = true
config.action_mailer.perform_deliveries = true

config.action_mailer.smtp_settings = {
  address: "#{login}.mailexam.io",
  port: port,
  user_name: login,
  password: ENV.fetch("MAILEXAM_PASSWORD"),
  authentication: :plain,
  enable_starttls_auto: [587, 2525].include?(port),
}

config.action_mailer.default_options = {
  from: ENV.fetch("MAIL_FROM", "noreply@example.test"),
}

4. Mailer and template

bin/rails generate mailer TestMailer test_email

app/mailers/test_mailer.rb:

class TestMailer < ApplicationMailer
  def test_email
    @body = params[:body]

    mail(
      to: params[:to],
      subject: params[:subject]
    )
  end
end

app/views/test_mailer/test_email.text.erb:

<%= @body %>

5. Sending a test email

Via console

bin/rails console

TestMailer.with(
  to: "user@example.test",
  subject: "Ruby on Rails + Mailexam",
  body: "Mailexam test from Rails"
).test_email.deliver_now

Via controller

app/controllers/mail_controller.rb:

class MailController < ActionController::API
  def test
    payload = JSON.parse(request.body.read.presence || "{}")

    TestMailer.with(
      to: payload["to"].presence || "user@example.test",
      subject: payload["subject"].presence || "Ruby on Rails + Mailexam",
      body: payload["body"].presence || "Mailexam test from Ruby on Rails"
    ).test_email.deliver_now

    render json: { status: "ok" }
  end
end

config/routes.rb:

Rails.application.routes.draw do
  post "mail/test", to: "mail#test"
end

Start and verify:

bin/rails server

curl -X POST http://127.0.0.1:3000/mail/test \
  -H 'Content-Type: application/json' \
  -d '{"to":"user@example.test","subject":"Test","body":"Hello"}'

The message will appear in the Mailexam dashboard → your project → inbox.

6. Local development and CI

Environment Recommendation
local .env + dotenv-rails
CI secrets MAILEXAM_LOGIN, MAILEXAM_PASSWORD in GitLab CI/CD Variables

Example for .gitlab-ci.yml:

variables:
  MAILEXAM_LOGIN: $MAILEXAM_LOGIN
  MAILEXAM_PASSWORD: $MAILEXAM_PASSWORD
  MAILEXAM_PORT: "587"
  MAIL_FROM: "noreply@example.test"

After an integration test, verify delivery via the Mailexam API.

In tests you can use delivery_method = :test and ActionMailer::Base.deliveries.

7. Common issues

TLS or authentication failed error

  • address — {login}.mailexam.io, user_name — the same login from the email.
  • Login and password are a pair from the email for one project.

Port 587

  • enable_starttls_auto must be true.

Message not in the dashboard

  • View the inbox of the same Mailexam project.
  • Make sure perform_deliveries = true and production is not accidentally using :test delivery.

Variables not picked up

  • Restart bin/rails server after changing .env.

See also