跳转至

FastAPI

适用于 FastAPI（Python 3.10+）应用的集成指南。Mailexam 通过 smtplib 作为 SMTP 服务器接入；发送逻辑可提取到独立模块，由异步处理器调用。

前置条件

  • 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 fastapi uvicorn python-dotenv email-validator

requirements.txt：

fastapi>=0.115
uvicorn[standard]>=0.32
python-dotenv>=1.0
email-validator>=2.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，而非真实收件人。

备选端口

MAILEXAM_PORT=587

MAILEXAM_PORT=2525

MAILEXAM_PORT=25

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

3. 邮件发送模块

与 Flask 相同方式：

# 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 in (587, 2525):
            smtp.starttls()
        smtp.login(login, password)
        smtp.send_message(msg)

smtplib 为同步库 — 在异步应用中通过 asyncio.to_thread 调用，避免阻塞事件循环。

4. FastAPI 路由

# main.py
import asyncio

from dotenv import load_dotenv
from fastapi import FastAPI
from pydantic import BaseModel, EmailStr

from mail import send_test

load_dotenv()

app = FastAPI()


class SendRequest(BaseModel):
    to: EmailStr = "user@example.test"
    subject: str = "FastAPI + Mailexam"
    body: str = "来自 FastAPI 的 Mailexam 测试"


@app.post("/mail/test")
async def mail_test(payload: SendRequest):
    await asyncio.to_thread(
        send_test,
        to=str(payload.to),
        subject=payload.subject,
        body=payload.body,
    )
    return {"status": "ok"}

启动并验证：

uvicorn main:app --reload --host 127.0.0.1 --port 8000

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

API 文档：http://127.0.0.1:8000/docs

邮件将出现在 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 项目的收件箱。
  • 检查 /mail/test 响应及 uvicorn 日志。

事件循环阻塞

  • 不要在 async def 中直接调用 send_test() — 使用 asyncio.to_thread() 或后台任务。

环境变量未生效

  • 在应用启动时调用 load_dotenv()。
  • 通过 systemd/Docker 运行时，将变量传入容器环境。

参见