Base URL https://paimian.cn
进入后台 健康检查

Gomail Suite API 调用文档

这个服务把 SMTP 发信、IP 归属地查询、二维码生成整合到同一个 HTTP API。后台接口使用管理员令牌，业务接口使用带权限的 API Key。

SMTP配置、测试、发信
API Keys哈希存储，只返回一次明文
IP LookupMaxMind + QQWry
QR CodePNG / SVG 输出

认证方式

后台管理接口

用于配置 SMTP、创建和撤销 API Key、后台测试邮件。任选一种 Header：

Authorization: Bearer <ADMIN_TOKEN>
X-Admin-Token: <ADMIN_TOKEN>

业务调用接口

用于发信、IP 查询、二维码生成。必须使用创建 API Key 时返回的明文 Key：

Authorization: Bearer <API_KEY>
API Key 明文只在创建时返回一次；数据库只保存 SHA-256 哈希。请在创建后立即保存明文 Key。

路由总览

方法路径认证说明
GET/healthz无服务健康检查
GET/api/admin/smtpADMIN_TOKEN读取 SMTP 配置，不返回密码明文
PUT/api/admin/smtpADMIN_TOKEN保存 SMTP 配置
POST/api/admin/test-emailADMIN_TOKEN用当前 SMTP 配置发送测试邮件
GET/api/admin/api-keysADMIN_TOKEN查看 API Key 列表
POST/api/admin/api-keysADMIN_TOKEN创建 API Key
DELETE/api/admin/api-keys/{id}ADMIN_TOKEN撤销 API Key
POST/api/v1/mail/sendsend:mail发送邮件
GET/api/v1/ip/{ip}lookup:ip查询指定 IP
GET/api/v1/ip/melookup:ip查询调用方 IP
GET / POST/api/v1/qrcodegenerate:qrcode生成 PNG 或 SVG 二维码

错误格式

JSON 接口失败时统一返回：

{
  "error": "invalid api key"
}

SMTP 保存、测试或发信失败时会额外返回 status、kind、hint，用于判断是 DNS、端口、加密、认证还是投递限制问题。

{
  "error": "smtp delivery failed: 535 5.7.8 authentication failed",
  "status": 502,
  "kind": "auth",
  "hint": "SMTP authentication failed. Check the username, password, and app password or authorization code."
}
状态码场景
400参数格式错误，例如邮箱地址、IP、二维码颜色不合法
401缺少或错误的管理员令牌 / API Key
403API Key 缺少接口所需权限
404SMTP 未配置或撤销的 Key 不存在
409发信前 SMTP 尚未配置
502SMTP 服务连接、认证或投递失败

后台接口：SMTP 配置

GET/api/admin/smtpADMIN_TOKEN

读取当前 SMTP 配置。响应不会包含密码明文，只返回 password_set。

curl -H "Authorization: Bearer <ADMIN_TOKEN>" \
  "https://paimian.cn/api/admin/smtp"
PUT/api/admin/smtpADMIN_TOKEN

保存 SMTP 配置。更新时不传 password 会保留旧密码。

字段类型说明
hoststringSMTP 主机，必填
portnumber1 到 65535，常用 587 或 465
usernamestringSMTP 用户名；为空时允许无认证 relay
passwordstringSMTP 密码；更新时可省略
from_emailstring发件邮箱，必须是邮箱地址
from_namestring发件人显示名
encryptionstringstarttls、tls、none。tls 对应常说的 SSL/SMTPS，通常端口 465；starttls 通常端口 587；none 只建议内网 relay。
 
curl -X PUT "https://paimian.cn/api/admin/smtp" \
  -H "Authorization: Bearer <ADMIN_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "host": "smtp.example.com",
    "port": 587,
    "username": "[email protected]",
    "password": "smtp-password",
    "from_email": "[email protected]",
    "from_name": "Gomail",
    "encryption": "starttls"
  }'
POST/api/admin/test-emailADMIN_TOKEN

使用当前 SMTP 配置发送测试邮件。

curl -X POST "https://paimian.cn/api/admin/test-email" \
  -H "Authorization: Bearer <ADMIN_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "to": ["[email protected]"],
    "subject": "SMTP test",
    "text": "hello from Gomail"
  }'

后台接口：API Key 管理

权限可调用接口
send:mailPOST /api/v1/mail/send
lookup:ipGET /api/v1/ip/{ip}、GET /api/v1/ip/me
generate:qrcodeGET /api/v1/qrcode、POST /api/v1/qrcode
POST/api/admin/api-keysADMIN_TOKEN

创建 API Key。expires_at 可选，必须是 RFC3339 时间。明文 key 只返回一次。

curl -X POST "https://paimian.cn/api/admin/api-keys" \
  -H "Authorization: Bearer <ADMIN_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "production-app",
    "permissions": ["send:mail", "lookup:ip", "generate:qrcode"],
    "expires_at": "2026-12-31T00:00:00Z"
  }'
{
  "api_key": {
    "id": 1,
    "name": "production-app",
    "prefix": "gm_xxxxxxxx",
    "permissions": ["send:mail", "lookup:ip", "generate:qrcode"],
    "created_at": "2026-05-30T00:00:00Z",
    "expires_at": "2026-12-31T00:00:00Z"
  },
  "key": "gm_full_plain_key_returned_once"
}
GET/api/admin/api-keysADMIN_TOKEN

列出所有 API Key 的元数据，不返回明文 Key。

DELETE/api/admin/api-keys/{id}ADMIN_TOKEN

撤销一个仍处于 active 状态的 API Key。

curl -X DELETE "https://paimian.cn/api/admin/api-keys/1" \
  -H "Authorization: Bearer <ADMIN_TOKEN>"

后台工具接口

这些接口使用管理员令牌，方便后台或脚本直接测试 IP 查询和二维码生成。

GET/api/admin/ip/lookup?ip=8.8.8.8ADMIN_TOKEN
GET/api/admin/qrcode?content=Hello&size=512&format=pngADMIN_TOKEN

响应是图片二进制，Content-Type 为 image/png 或 image/svg+xml。

业务接口：发送邮件

POST/api/v1/mail/sendsend:mail

调用方不能指定发件人，发件人固定使用 SMTP 配置里的 from_email 和 from_name。

字段类型说明
tostring[]主收件人
ccstring[]抄送，可选
bccstring[]密送，可选，不会写入邮件头
subjectstring必填
textstring纯文本正文；text 和 html 至少一个
htmlstringHTML 正文；和 text 同时存在时发送 multipart/alternative
reply_tostring回复地址，可选
 
curl -X POST "https://paimian.cn/api/v1/mail/send" \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "to": ["[email protected]"],
    "cc": ["[email protected]"],
    "bcc": ["[email protected]"],
    "subject": "Hello",
    "text": "Plain text body",
    "html": "<p>HTML body</p>",
    "reply_to": "[email protected]"
  }'
{
  "status": "sent",
  "recipients": 3
}

业务接口：IP 查询

GET/api/v1/ip/{ip}lookup:ip
GET/api/v1/ip?ip={ip}lookup:ip

查询指定 IP 的国家、省份、城市、ISP、经纬度和数据源。

curl "https://paimian.cn/api/v1/ip/8.8.8.8" \
  -H "Authorization: Bearer <API_KEY>"
{
  "ip": "8.8.8.8",
  "country": "美国",
  "country_code": "US",
  "province": "",
  "region": "",
  "city": "",
  "isp": "谷歌",
  "latitude": 37.751,
  "longitude": -97.822,
  "source": "MaxMind"
}
GET/api/v1/ip/melookup:ip

按 CF-Connecting-IP、X-Real-IP、X-Forwarded-For、连接地址的顺序识别调用方 IP。

业务接口：二维码生成

GET/api/v1/qrcodegenerate:qrcode
POST/api/v1/qrcodegenerate:qrcode

返回二维码图片二进制。GET 使用 query 参数；POST 可以提交 JSON 或表单。

参数默认值说明
content无二维码内容，必填，最大 4096 字节
size256图片尺寸，范围 64 到 2048
formatpngpng 或 svg
fg_color#000000前景色，6 位十六进制颜色
bg_color#FFFFFF背景色，6 位十六进制颜色
 
curl "https://paimian.cn/api/v1/qrcode?content=https%3A%2F%2Fexample.com&size=512&format=png" \
  -H "Authorization: Bearer <API_KEY>" \
  -o qrcode.png
curl -X POST "https://paimian.cn/api/v1/qrcode" \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "https://example.com",
    "size": 512,
    "format": "svg",
    "fg_color": "#111827",
    "bg_color": "#FFFFFF"
  }' \
  -o qrcode.svg