命令行接口 (CLI)¶

mailexam-cli 是 Mailexam REST API 的官方命令行工具。适用于本地调试、QA 和 CI/CD，无需编写 Python/Node.js 脚本或冗长的 curl 命令。

典型流程：应用通过 SMTP 发送邮件，流水线中一条命令等待送达并验证内容：

mailexam email assert --subject "CI 检查" --contains "你好"

何时使用 CLI

CI/CD — wait 和 assert 命令，退出码清晰。
快速检查 — 在终端列出项目、收件箱和邮件。
直接调用 REST API — 需要完整灵活性（创建项目、自定义逻辑）时，请参阅 REST API 与 Swagger UI。

安装¶

go install从源码构建验证

需要 Go 1.22+：

go install github.com/mailexam/mailexam-cli/cmd/mailexam@latest

二进制文件位于 $GOPATH/bin 或 $HOME/go/bin，请确保该目录在 PATH 中。

git clone https://github.com/mailexam/mailexam-cli.git
cd mailexam-cli
go build -o mailexam ./cmd/mailexam
sudo mv mailexam /usr/local/bin/   # 可选

mailexam version
mailexam --help

配置¶

API 令牌在控制台获取。这不是 SMTP 密码 — 令牌仅用于 REST API（见 REST API — 认证）。

变量	说明
`MAILEXAM_API_TOKEN`	API 令牌（必填）
`MAILEXAM_API_BASE`	基础 URL（默认 `https://mailexam.cn/api/v1`）
`MAILEXAM_PROJECT_UUID`	默认项目 UUID
`MAILEXAM_INBOX_UUID`	默认收件箱 UUID

也可通过标志传入：--token、--base、--project、--inbox。

区域域名

区域	`MAILEXAM_API_BASE`
俄罗斯	`https://mailexam.ru/api/v1`
中国	`https://mailexam.cn/api/v1`
国际	`https://mailexam.io/api/v1`

本地使用示例：

export MAILEXAM_API_TOKEN="your_token"
export MAILEXAM_PROJECT_UUID="536a47df-5aad-44d0-8163-a39bb55abe0b"
export MAILEXAM_API_BASE="https://mailexam.cn/api/v1"

CI/CD 中的密钥

不要将令牌提交到仓库。在 GitLab CI、GitHub Actions 或其他流水线密钥中设置 MAILEXAM_API_TOKEN。

CI/CD 流程¶

sequenceDiagram
    participant App as 应用
    participant SMTP as Mailexam SMTP
    participant CLI as mailexam CLI
    participant API as REST API

    App->>SMTP: sendMail()
    Note over SMTP: 邮件进入 sandbox
    CLI->>API: 轮询 GET /email
    API-->>CLI: 找到邮件
    CLI->>CLI: 断言主题、正文
    Note over CLI: 退出码 0 或 1

应用通过 SMTP 发送邮件（见集成示例）。
流水线执行 mailexam email wait 或 mailexam email assert。
CLI 默认每 2 秒轮询 API，直至超时。

命令参考¶

所有命令均支持全局标志：--token、--base、--project、--inbox。

项目¶

命令	说明
`mailexam project list`	列出项目
`mailexam project get UUID`	获取项目详情

使用 --json 输出原始 API JSON。

mailexam project list
mailexam project list --json
mailexam project get 536a47df-5aad-44d0-8163-a39bb55abe0b

可通过 project list 或控制台查看项目 UUID。

收件箱¶

命令	说明
`mailexam inbox list`	列出收件箱（需 `--project` 或 `MAILEXAM_PROJECT_UUID`）
`mailexam inbox get UUID`	获取收件箱详情

mailexam inbox list --project $MAILEXAM_PROJECT_UUID
mailexam inbox get deab7974-a252-4412-9169-b965116b63cf

邮件¶

命令	说明
`mailexam email list`	列出收件箱中的邮件
`mailexam email get UUID`	获取完整邮件
`mailexam email wait`	等待匹配过滤条件的邮件
`mailexam email assert`	等待并验证内容
`mailexam email delete UUID`	删除邮件

对于 email list、wait 和 assert，设置 MAILEXAM_PROJECT_UUID 即可：CLI 会选择默认收件箱或列表中的第一个。使用 --inbox 或 MAILEXAM_INBOX_UUID 指定收件箱。

列表与查看¶

mailexam email list
mailexam email list --json

mailexam email get e2f9a506-d766-4935-be11-c413384de020
mailexam email get e2f9a506-d766-4935-be11-c413384de020 --format text
mailexam email get e2f9a506-d766-4935-be11-c413384de020 --format html
mailexam email get e2f9a506-d766-4935-be11-c413384de020 --format uuid

--format 选项：json（默认）、text、html、raw、uuid。

等待邮件（`wait`）¶

至少需要一个过滤条件：--subject、--to 或 --from。

mailexam email wait --subject "CI 检查"
mailexam email wait --subject "CI 检查" --subject-exact
mailexam email wait --to "user@example.com" --timeout 60 --interval 3
mailexam email wait --subject "验证码" --format text

标志	默认值	说明
`--subject`	—	主题子串
`--subject-exact`	`false`	主题完全匹配
`--to`	—	收件人字段子串
`--from`	—	发件人字段子串
`--timeout`	`30`	超时（秒）
`--interval`	`2`	轮询间隔（秒）
`--format`	`json`	找到邮件后的输出格式

测试断言（`assert`）¶

流水线主命令：成功时输出 OK 并以退出码 0 结束。

mailexam email assert --subject "CI 检查" --contains "你好"
mailexam email assert --subject "验证码" --contains "123456" --contains "有效"
mailexam email assert --subject "报告" --matches 'total:\s+\d+'
mailexam email assert --subject "文件" --require-attachments
mailexam email assert --subject "文件" --attachment-count 2

标志	说明
`--contains`	正文须包含文本（可重复）
`--matches`	正文须匹配正则表达式
`--require-attachments`	邮件须有附件
`--attachment-count`	附件精确数量

正文检查优先使用纯文本部分；若无则使用 HTML。

附件¶

mailexam email get EMAIL_UUID --format json   # 查看附件 cid
mailexam email attachment download EMAIL_UUID --cid ATTACHMENT_CID -o report.pdf
mailexam email attachment download EMAIL_UUID --cid ATTACHMENT_CID -o -  # 输出到 stdout

CI/CD 示例¶

GitLab CI¶

integration_test:
  stage: test
  image: golang:1.22
  variables:
    MAILEXAM_API_BASE: "https://mailexam.cn/api/v1"
    MAILEXAM_PROJECT_UUID: "536a47df-5aad-44d0-8163-a39bb55abe0b"
  before_script:
    - go install github.com/mailexam/mailexam-cli/cmd/mailexam@latest
  script:
    - npm run send-test-email
    - mailexam email assert --subject "CI 检查" --contains "你好"
  # MAILEXAM_API_TOKEN — CI/CD Variables（masked）

GitHub Actions¶

- name: Install mailexam CLI
  run: go install github.com/mailexam/mailexam-cli/cmd/mailexam@latest

- name: Send test email
  run: npm run send-test-email

- name: Assert email delivered
  env:
    MAILEXAM_API_TOKEN: ${{ secrets.MAILEXAM_API_TOKEN }}
    MAILEXAM_API_BASE: https://mailexam.cn/api/v1
    MAILEXAM_PROJECT_UUID: 536a47df-5aad-44d0-8163-a39bb55abe0b
  run: mailexam email assert --subject "CI 检查" --contains "你好"

SMTP 凭据（MAILEXAM_LOGIN、MAILEXAM_PASSWORD）供应用发送邮件；API 令牌仅供 CLI 使用。

退出码¶

码	含义
`0`	成功
`1`	错误或 `assert` 失败
`2`	认证错误（HTTP 403）
`3`	等待邮件超时

GitLab CI 与 GitHub Actions 在非零退出码时会失败 — 无需额外包装脚本。

常见问题¶

api token is required

设置 MAILEXAM_API_TOKEN 或使用 --token。

退出码 2（403）

令牌不完整或属于其他账户。见 REST API — 常见问题。

退出码 3（timeout）

邮件尚未送达 — 增大 --timeout。
邮件进入其他项目 — 核对 SMTP 登录名与 MAILEXAM_PROJECT_UUID。
主题不匹配 — 检查精确值或去掉 --subject-exact。

project or inbox is required

设置 MAILEXAM_PROJECT_UUID 或 --project。指定收件箱时使用 --inbox。