跳转至

Django

适用于 Django（4.2 LTS 和 5.x）项目的集成指南。Mailexam 通过内置 SMTP 后端 django.core.mail 接入 — 在 settings.py 中配置并调用 send_mail 即可。

前置条件

  • Mailexam 账户，以及已创建并具备 SMTP 凭据的项目。
  • Python 3.10+ 及已安装的 Django 项目。

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

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

1. 依赖

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

requirements.txt：

django>=5.0
python-dotenv>=1.0

2. 环境变量

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

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

Django 设置中的主机：{MAILEXAM_LOGIN}.mailexam.cn。

发件人地址

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

备选端口

MAILEXAM_PORT=587

在 settings.py 中：EMAIL_USE_TLS = True。

MAILEXAM_PORT=2525

EMAIL_USE_TLS = True。

MAILEXAM_PORT=25

EMAIL_USE_TLS = False。

3. settings.py 配置

在文件顶部加载 .env（可选，用于本地开发）：

from pathlib import Path

from dotenv import load_dotenv

BASE_DIR = Path(__file__).resolve().parent.parent
load_dotenv(BASE_DIR / ".env")

Mailexam 邮件配置块：

import os

MAILEXAM_LOGIN = os.environ["MAILEXAM_LOGIN"]
MAILEXAM_PASSWORD = os.environ["MAILEXAM_PASSWORD"]
MAILEXAM_PORT = int(os.environ.get("MAILEXAM_PORT", "587"))

EMAIL_BACKEND = "django.core.mail.backends.smtp.EmailBackend"
EMAIL_HOST = f"{MAILEXAM_LOGIN}.mailexam.cn"
EMAIL_PORT = MAILEXAM_PORT
EMAIL_USE_TLS = MAILEXAM_PORT in (587, 2525)
EMAIL_HOST_USER = MAILEXAM_LOGIN
EMAIL_HOST_PASSWORD = MAILEXAM_PASSWORD
DEFAULT_FROM_EMAIL = os.environ.get("MAIL_FROM", "noreply@example.test")

4. 发送测试邮件

通过 shell

python manage.py shell

from django.core.mail import send_mail

send_mail(
    "Django + Mailexam",
    "来自 Django 的 Mailexam 测试",
    None,  # 使用 DEFAULT_FROM_EMAIL
    ["user@example.test"],
)

通过视图

# myapp/views.py
import json

from django.conf import settings
from django.core.mail import send_mail
from django.http import JsonResponse
from django.views.decorators.http import require_POST


@require_POST
def mail_test(request):
    data = json.loads(request.body or "{}")
    send_mail(
        subject=data.get("subject", "Django + Mailexam"),
        message=data.get("body", "来自 Django 的 Mailexam 测试"),
        from_email=settings.DEFAULT_FROM_EMAIL,
        recipient_list=[data.get("to", "user@example.test")],
    )
    return JsonResponse({"status": "ok"})

# myapp/urls.py
from django.urls import path

from . import views

urlpatterns = [
    path("mail/test", views.mail_test, name="mail_test"),
]

启动并验证：

python manage.py runserver

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

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

5. 本地开发与 CI

环境 建议
local .env + load_dotenv 或在 shell 中 export 变量
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 验证投递。

无需网络的单元测试使用 EMAIL_BACKEND = "django.core.mail.backends.locmem.EmailBackend"。

6. 常见问题

TLS 或连接错误

  • EMAIL_HOST 须为 {login}.mailexam.cn，其中 {login} 与 EMAIL_HOST_USER / MAILEXAM_LOGIN 相同。
  • 登录名和密码为邮件成对凭据；勿混用不同项目的凭据。
  • 587 端口启用 EMAIL_USE_TLS = True。

控制台中看不到邮件

  • 确认查看的是同一 Mailexam 项目的收件箱。
  • 确认生产环境未将 EMAIL_BACKEND 覆盖为 console 或 file 后端。

设置未生效

  • 修改 settings.py 后重启 runserver。
  • 生产环境在进程（gunicorn/uwsgi）中设置环境变量，而非仅依赖磁盘上的 .env 文件。

参见