跳转至

1C-Bitrix

适用于 1C-Bitrix：网站管理系统 20+（D7）站点的集成指南。Mailexam 通过 mailexam.smtp 模块与 OnBeforePhpMailerInit 事件处理程序作为 SMTP 服务器接入。

前置条件

  • Mailexam 账户，以及已创建并具备 SMTP 凭据的项目。
  • 1C-Bitrix 20+ 与 PHP 8.0+。

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

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

1. 在 .settings.php 中配置变量

在 bitrix/.settings.php 中添加 environment 段（勿将密码提交到公开仓库）：

'environment' => [
    'value' => [
        'MAILEXAM_LOGIN' => 'YOUR_LOGIN',
        'MAILEXAM_PASSWORD' => 'YOUR_PASSWORD',
        'MAILEXAM_PORT' => '587',
        'MAIL_FROM' => 'noreply@example.test',
    ],
    'readonly' => true,
],

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

发件人地址

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

备选端口

'MAILEXAM_PORT' => '587',

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

'MAILEXAM_PORT' => '2525',

'MAILEXAM_PORT' => '25',

不使用 STARTTLS 的 plain SMTP。

2. 安装模块

从 GitHub 参考仓库 复制 local/modules/mailexam.smtp 与 local/tools/mailexam 到您的站点，然后安装模块：

  • 在管理后台：Marketplace → 已安装的解决方案；
  • 或通过 CLI（若主机支持）。

模块包含：

  • lib/smtpsender.php — 587 端口的 STARTTLS SMTP 客户端；
  • lib/eventhandler.php — 通过 OnBeforePhpMailerInit 配置 PHPMailer；
  • local/tools/mailexam/mail_test.php — 测试端点。

3. SMTP 发送器（节选）

// local/modules/mailexam.smtp/lib/smtpsender.php
public function send(string $to, string $subject, string $body, ?string $from = null): void
{
    if (!Config::isConfigured()) {
        throw new \RuntimeException('MAILEXAM_LOGIN and MAILEXAM_PASSWORD must be set');
    }

    $host = Config::getHost(); // {login}.mailexam.cn
    $port = Config::getPort();

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

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

完整模块见 GitHub：mailexam/1C-Bitrix。

4. 测试发送

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

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

配置 MAILEXAM_LOGIN 与 MAILEXAM_PASSWORD 后，Bitrix 系统邮件（注册、表单、通知）也会经 Mailexam SMTP 发送。

5. 本地开发与 CI

环境 建议
local bitrix/.settings.php 中的 environment 段
CI pipeline 变量中的 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. 常见问题

复制后找不到模块

  • 路径必须为 local/modules/mailexam.smtp，然后在管理后台安装模块。

TLS 或认证失败

  • 主机必须为 {login}.mailexam.cn，用户名为欢迎邮件中的同一登录名。
  • 登录名与密码须来自同一项目的欢迎邮件。

测试脚本返回 404

  • 检查 URL /local/tools/mailexam/mail_test.php。
  • 确认 Web 服务器可访问 local/tools 目录。

控制台中看不到邮件

  • 打开同一 Mailexam 项目的收件箱。
  • 检查 mail_test.php 返回的 JSON 错误与 PHP 日志。

另请参阅