跳转至

Magento

适用于 Magento 2 Open Source 或 Commerce 2.4+ 商店的集成指南。Mailexam 通过自定义模块作为 SMTP 服务器接入，可路由 Magento 邮件传输并提供测试端点。

前置条件

  • Mailexam 账户，以及已创建并具备 SMTP 凭据的项目。
  • Magento 2.4+ 与 PHP 8.1+。

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

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

1. 在 env.php 中配置环境变量

在 app/etc/env.php 的 env 段中添加（勿将密码提交到公开仓库）：

'env' => [
    'MAILEXAM_LOGIN' => 'YOUR_LOGIN',
    'MAILEXAM_PASSWORD' => 'YOUR_PASSWORD',
    'MAILEXAM_PORT' => '587',
    'MAIL_FROM' => 'noreply@example.test',
],

代码中的 SMTP 主机：YOUR_LOGIN.mailexam.cn（参考实现中域名为 mailexam.io，请按您账户欢迎邮件中的主机填写）。

发件人地址

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

备选端口

'MAILEXAM_PORT' => '587',

模块对端口 587 和 2525 使用 STARTTLS。

'MAILEXAM_PORT' => '2525',

'MAILEXAM_PORT' => '25',

不使用 STARTTLS 的 plain SMTP。

2. 安装模块

从 GitHub 参考仓库 复制 app/code/Mailexam/Smtp 到您的商店，然后启用：

bin/magento module:enable Mailexam_Smtp
bin/magento setup:upgrade
bin/magento cache:flush

模块包含：

  • Model/SmtpSender.php — 587 端口的 STARTTLS SMTP 客户端；
  • Plugin/Mail/TransportPlugin.php — 配置凭据后将 Magento 事务邮件路由到 Mailexam；
  • Controller/Mail/Test.php — 测试端点 POST /mailexam/mail/test。

完整源码见 GitHub：mailexam/Magento。

3. SMTP 发送器（节选）

// app/code/Mailexam/Smtp/Model/SmtpSender.php
public function send(string $to, string $subject, string $body, ?string $from = null): void
{
    if (!$this->config->isConfigured()) {
        throw new \RuntimeException('MAILEXAM_LOGIN and MAILEXAM_PASSWORD must be set');
    }

    $host = $this->config->getHost(); // {login}.mailexam.io
    $port = $this->config->getPort();

    if (in_array($port, [587, 2525], true)) {
        $this->sendWithStartTls(/* ... */);
        return;
    }

    $this->sendPlain(/* ... */);
}

4. 测试发送

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

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

设置 MAILEXAM_LOGIN 和 MAILEXAM_PASSWORD 后，订单确认等 Magento 系统邮件也会经 Mailexam SMTP 发送。

5. 本地开发与 CI

环境 建议
local 在 app/etc/env.php 的 env 段中配置
CI 在流水线变量中设置 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 确认投递。

6. 常见问题

复制后找不到模块

  • 路径须为 app/code/Mailexam/Smtp，然后运行 bin/magento setup:upgrade。

TLS 或认证失败

  • 主机应为 {login}.mailexam.cn（或欢迎邮件中的主机），用户名为邮件中的同一登录名。
  • 登录名与密码须为同一项目欢迎邮件中的成对凭据。

测试端点返回 404

  • 运行 bin/magento cache:flush，并确认模块已启用。

控制台中看不到邮件

  • 请查看同一 Mailexam 项目的收件箱。
  • 检查 var/log/exception.log 以及测试端点返回的 JSON 错误信息。

参见