Flask¶

适用于 Flask（Python 3.10+）应用的集成指南。Mailexam 通过标准 smtplib 模块作为 SMTP 服务器接入；最小 Flask 应用即可提供测试路由。

前置条件¶

Mailexam 账户，以及已创建并具备 SMTP 凭据的项目。
Python 3.10+ 及虚拟环境。

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

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

1. 依赖¶

python3 -m venv .venv
source .venv/bin/activate
pip install flask python-dotenv

requirements.txt：

flask>=3.0
python-dotenv>=1.0

2. 环境变量¶

项目根目录的 .env 文件（勿将密码提交到 git）：

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

主机由登录名构建：{MAILEXAM_LOGIN}.mailexam.cn。

发件人地址

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

备选端口¶

587 + STARTTLS（推荐）252525，无 TLS

MAILEXAM_PORT=587

MAILEXAM_PORT=2525

MAILEXAM_PORT=25

25 端口在代码中不要调用 starttls()（见下方模块）。

3. 邮件发送模块¶

# mail.py
import os
import smtplib
from email.message import EmailMessage


def smtp_host() -> str:
    login = os.environ["MAILEXAM_LOGIN"]
    return f"{login}.mailexam.cn"


def send_test(*, to: str, subject: str, body: str) -> None:
    login = os.environ["MAILEXAM_LOGIN"]
    password = os.environ["MAILEXAM_PASSWORD"]
    port = int(os.environ.get("MAILEXAM_PORT", "587"))
    mail_from = os.environ.get("MAIL_FROM", "noreply@example.test")

    msg = EmailMessage()
    msg["From"] = mail_from
    msg["To"] = to
    msg["Subject"] = subject
    msg.set_content(body)

    with smtplib.SMTP(smtp_host(), port, timeout=30) as smtp:
        if port == 587 or port == 2525:
            smtp.starttls()
        smtp.login(login, password)
        smtp.send_message(msg)

4. Flask 路由¶

# app.py
import os

from dotenv import load_dotenv
from flask import Flask, jsonify, request

from mail import send_test

load_dotenv()

app = Flask(__name__)


@app.post("/mail/test")
def mail_test():
    data = request.get_json(force=True, silent=True) or {}
    to = data.get("to", "user@example.test")
    subject = data.get("subject", "Flask + Mailexam")
    body = data.get("body", "来自 Flask 的 Mailexam 测试")

    send_test(to=to, subject=subject, body=body)
    return jsonify({"status": "ok"})


if __name__ == "__main__":
    app.run(host="127.0.0.1", port=5000, debug=True)

启动并验证：

python app.py

curl -X POST http://127.0.0.1:5000/mail/test \
  -H 'Content-Type: application/json' \
  -d '{"to":"user@example.test","subject":"测试","body":"你好"}'

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

5. 本地开发与 CI¶

环境	建议
`local`	带个人 Mailexam 项目的 `.env`
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 验证投递。

6. 常见问题¶

TLS 或连接错误

主机须为 {login}.mailexam.cn，其中 {login} 与邮件中的 MAILEXAM_LOGIN 相同。
登录名和密码为邮件成对凭据；勿混用不同项目的凭据。
587 端口在 login() 前调用 smtp.starttls()。

控制台中看不到邮件

确认查看的是同一 Mailexam 项目的收件箱。
检查 Flask 日志及发送时的 traceback。

环境变量未生效

在读取 os.environ 前调用 load_dotenv()。
生产环境通过进程环境或 CI 密钥传递变量。