跳转至

Ruby on Rails

适用于 Ruby on Rails 7.x / 8.x 应用的集成指南。Mailexam 通过 Action Mailer 及 config 中的 SMTP 设置接入。

前置条件

  • Mailexam 账户，以及已创建并具备 SMTP 凭据的项目。
  • Ruby 3.2+ 及 Rails 应用（rails new）。

从项目的欢迎邮件（或控制台）中复制：

  • YOUR_LOGIN — SMTP 登录名（例如 xxxxx）；
  • YOUR_PASSWORD — SMTP 密码（与登录名成对的唯一凭据）；
  • 主机 — YOUR_LOGIN.mailexam.cn（与登录名一致）。

1. 依赖

在 Gemfile 中加载开发环境的 .env：

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

bundle install

2. 环境变量

项目根目录的 .env 文件（加入 .gitignore）：

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

SMTP 主机：YOUR_LOGIN.mailexam.cn。

发件人地址

MAIL_FROM 可以是任意测试地址——邮件进入 Mailexam，而非真实收件人。

备选端口

MAILEXAM_PORT=587

enable_starttls_auto: true

MAILEXAM_PORT=2525

STARTTLS，与 587 相同。

MAILEXAM_PORT=25

enable_starttls_auto: false

3. Action Mailer 配置

config/environments/development.rb（生产环境类似，通过服务器环境变量）：

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.cn",
  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 与模板

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. 发送测试邮件

通过控制台

bin/rails console

TestMailer.with(
  to: "user@example.test",
  subject: "Ruby on Rails + Mailexam",
  body: "来自 Rails 的 Mailexam 测试"
).test_email.deliver_now

通过控制器

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 || "来自 Ruby on Rails 的 Mailexam 测试"
    ).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

启动并验证：

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":"测试","body":"你好"}'

邮件将出现在 Mailexam 控制台 → 您的项目 → 收件箱。

6. 本地开发与 CI

环境 建议
local .env + dotenv-rails
CI GitLab CI/CD Variables 中的密钥 MAILEXAM_LOGIN、MAILEXAM_PASSWORD

.gitlab-ci.yml 示例：

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

集成测试后，通过 Mailexam API 验证投递。

测试中可使用 delivery_method = :test 和 ActionMailer::Base.deliveries。

7. 常见问题

TLS 或认证失败

  • address — {login}.mailexam.cn，user_name — 邮件中的同一登录名。
  • 登录名和密码为同一项目的邮件成对凭据。

587 端口

  • enable_starttls_auto 须为 true。

控制台中看不到邮件

  • 查看同一 Mailexam 项目的收件箱。
  • 确认 perform_deliveries = true，且生产环境未误用 :test 投递方式。

变量未生效

  • 修改 .env 后重启 bin/rails server。

参见