WordPress¶

适用于 WordPress 6.x 网站的集成指南。Mailexam 通过内置的 wp_mail() 与 phpmailer_init 钩子（PHPMailer）作为 SMTP 服务器接入。

前置条件¶

Mailexam 账户，以及已创建并具备 SMTP 凭据的项目。
WordPress 6+ 与 PHP 8.0+。

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

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

1. 在 `wp-config.php` 中定义常量¶

在 /* That's all, stop editing! */ 之前添加（勿将密码提交到公开仓库）：

define('MAILEXAM_LOGIN', 'YOUR_LOGIN');
define('MAILEXAM_PASSWORD', 'YOUR_PASSWORD');
define('MAILEXAM_PORT', 587);
define('MAIL_FROM', 'noreply@example.test');

SMTP 主机：YOUR_LOGIN.mailexam.cn。

发件人地址

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

备选端口¶

587 + STARTTLS（推荐）2525465（SMTPS）25（无 TLS）

define('MAILEXAM_PORT', 587);

在 MU 插件中：$phpmailer->SMTPSecure = 'tls';

define('MAILEXAM_PORT', 2525);

define('MAILEXAM_PORT', 465);

$phpmailer->SMTPSecure = 'ssl';

define('MAILEXAM_PORT', 25);

$phpmailer->SMTPSecure = '';

2. SMTP 必用插件（MU）¶

创建文件 wp-content/mu-plugins/mailexam-smtp.php（若无 mu-plugins 目录请先创建）：

<?php
/**
 * Plugin Name: Mailexam SMTP
 * Description: 通过 Mailexam SMTP 发送 WordPress 邮件
 */

add_action('phpmailer_init', static function ($phpmailer): void {
    if (!defined('MAILEXAM_LOGIN') || !defined('MAILEXAM_PASSWORD')) {
        return;
    }

    $login = MAILEXAM_LOGIN;
    $port = defined('MAILEXAM_PORT') ? (int) MAILEXAM_PORT : 587;

    $phpmailer->isSMTP();
    $phpmailer->Host = $login . '.mailexam.cn';
    $phpmailer->Port = $port;
    $phpmailer->SMTPAuth = true;
    $phpmailer->Username = $login;
    $phpmailer->Password = MAILEXAM_PASSWORD;

    if ($port === 465) {
        $phpmailer->SMTPSecure = 'ssl';
    } elseif (in_array($port, [587, 2525], true)) {
        $phpmailer->SMTPSecure = 'tls';
    } else {
        $phpmailer->SMTPSecure = '';
    }
});

add_filter('wp_mail_from', static function (): string {
    return defined('MAIL_FROM') ? MAIL_FROM : 'noreply@example.test';
});

必用插件会自动加载——无需在后台启用。

3. 测试发送¶

通过代码（临时写在主题 `functions.php`）¶

add_action('init', static function (): void {
    if (!isset($_GET['mailexam_mail_test']) || !current_user_can('manage_options')) {
        return;
    }

    $sent = wp_mail(
        'user@example.test',
        'WordPress + Mailexam',
        '来自 WordPress 的 Mailexam 测试'
    );

    wp_die($sent ? 'Sent' : 'Failed');
});

在浏览器中打开（需管理员登录）：
https://your-site.test/?mailexam_mail_test=1

验证后请删除上述代码。

通过 WP-CLI¶

wp eval "var_export(wp_mail('user@example.test', '检查', '来自 WordPress 的问候'));"

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

4. 本地开发与 CI¶

环境	建议
`local`	在 `wp-config.php` 或 `wp-config-local.php` 中配置常量
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 确认投递。

5. 常见问题¶

邮件未走 SMTP

确认文件位于 wp-content/mu-plugins/，而非 plugins/。
检查是否有其他 SMTP 插件以更高优先级覆盖了 phpmailer_init。

TLS 或认证失败

Host 应为 {login}.mailexam.cn，Username 为邮件中的同一登录名。
登录名与密码须为同一项目欢迎邮件中的成对凭据。

控制台中看不到邮件

请查看同一 Mailexam 项目的收件箱。
启用 define('WP_DEBUG', true);，并可临时安装 WP Mail Logging 排查。