Sign inSign up

jjyy225/tmpemail

By jjyy225

•Updated 3 months ago

SMTP catch-all + auth API. Per-mailbox dirs for multi-domain high concurrency. 10m TTL.

Image
0

191

jjyy225/tmpemail repository overview

⁠tmpemail

临时邮箱服务：SMTP 接收任意邮件并落盘，默认只保留 10 分钟，过期自动删除；HTTP API（Gin）鉴权后可按指定邮箱查询。

镜像：jjyy225/tmpemail

docker pull jjyy225/tmpemail:latest

⁠快速启动

docker run -d --name tmpemail \
  --restart unless-stopped \
  -p 25:25 \
  -p 50001:50001 \
  -e API_KEY=your-secret-key \
  -v tmpemail-data:/data \
  jjyy225/tmpemail:latest
端口用途
25SMTP 收信（接受任意 RCPT TO）
50001HTTP API（需 API_KEY）

健康检查（无需鉴权）：

curl http://127.0.0.1:50001/health

⁠环境变量

变量默认说明
API_KEYchangemeAPI 密钥（务必修改）
SMTP_ADDR:25SMTP 监听
HTTP_ADDR:50001HTTP 监听
DATA_DIR/data邮件 JSON 目录
MAIL_TTL10m邮件保留时长
PURGE_INTERVAL15s过期清理周期

⁠鉴权

/api/* 需要密钥（/health 除外），任选其一：

X-API-Key: your-secret-key
Authorization: Bearer your-secret-key
?api_key=your-secret-key

⁠核心能力：按指定邮箱查询

统一接口：GET|POST /api/mails（别名 /api/query、/api/mail）

用 to / email / mailbox 指定收件邮箱（三者等价）：

参数说明
to / email / mailbox指定邮箱。完整地址（含 @）→ 精确匹配；不含 @ → 子串匹配
modelatest = 该邮箱最后一封；all = 该邮箱 10 分钟内全部（默认 all）
from发件人过滤
subject主题过滤
limitall 时条数上限（默认 100，最大 500）
raw1/true 返回完整原始邮件
id按邮件 UUID 精确取一封
⁠1）指定邮箱 — 最后一封（验证码常用）
# 推荐
curl -H "X-API-Key: your-secret-key" \
  "http://127.0.0.1:50001/api/mails?mode=latest&[email protected]"

# 等价写法
curl -H "X-API-Key: your-secret-key" \
  "http://127.0.0.1:50001/api/mails?mode=latest&[email protected]"

curl -H "X-API-Key: your-secret-key" \
  "http://127.0.0.1:50001/api/mails?last=1&[email protected]"

POST：

curl -H "X-API-Key: your-secret-key" \
  -H "Content-Type: application/json" \
  -d '{"mode":"latest","email":"[email protected]"}' \
  http://127.0.0.1:50001/api/mails

成功响应要点：

{
  "ok": true,
  "mode": "latest",
  "email": "[email protected]",
  "found": true,
  "count": 1,
  "mail": {
    "id": "...",
    "from": "[email protected]",
    "to": ["[email protected]"],
    "subject": "Your code",
    "text": "code is 998877",
    "received_at": "2026-07-24T08:06:45Z",
    "expires_at": "2026-07-24T08:16:45Z",
    "ttl_left_s": 599
  },
  "mails": [ { "...": "同上" } ]
}

无邮件时：found=false，mail=null，count=0（HTTP 仍为 200）。客户端读 mail 即可。

⁠2）指定邮箱 — 10 分钟内全部
curl -H "X-API-Key: your-secret-key" \
  "http://127.0.0.1:50001/api/mails?mode=all&[email protected]&limit=50"

curl -H "X-API-Key: your-secret-key" \
  -H "Content-Type: application/json" \
  -d '{"mode":"all","email":"[email protected]","limit":50}' \
  http://127.0.0.1:50001/api/mails

响应：mails 数组，按收到时间倒序（最新在前）。

⁠3）按邮件 ID
curl -H "X-API-Key: your-secret-key" \
  "http://127.0.0.1:50001/api/mails/<uuid>?raw=1"

⁠Python 验证码轮询示例

import time, requests

API = "http://127.0.0.1:50001/api/mails"
HDR = {"X-API-Key": "your-secret-key"}
EMAIL = "[email protected]"

for _ in range(60):
    r = requests.get(API, headers=HDR, params={
        "mode": "latest",
        "email": EMAIL,   # 指定邮箱
    }, timeout=5)
    data = r.json()
    if data.get("found") and data.get("mail"):
        print(data["mail"]["subject"])
        print(data["mail"]["text"])
        break
    time.sleep(1)

⁠SMTP 测试发信

cat > /tmp/mail.txt <<'EOF'
From: [email protected]
To: [email protected]
Subject: test-code
Content-Type: text/plain

code=123456
EOF

curl --url "smtp://127.0.0.1:25" \
  --mail-from "[email protected]" \
  --mail-rcpt "[email protected]" \
  --upload-file /tmp/mail.txt

# 按该邮箱取最新一封
curl -H "X-API-Key: your-secret-key" \
  "http://127.0.0.1:50001/api/mails?mode=latest&[email protected]"

⁠存储布局（多域名 / 多邮箱 / 高并发）

/data/
  boxes/<domain>/<local>/<recv_ns>__<uuid>.json
  ids/<id前2位>/<uuid>.ref
  • 查询指定邮箱 只读对应目录，不扫全库
  • 文件名时间前缀，方便取最新
  • 无全局写锁，多 SMTP 并发写不同邮箱互不阻塞
  • 10 分钟 TTL 自动删文件并回收空目录

⁠注意

  1. 邮件默认 10 分钟过期并删除，不要当长期邮箱。
  2. 完整邮箱地址（含 @）为精确匹配，不会误匹配其它收件人。
  3. 公网务必设置强 API_KEY，并限制 50001 访问来源。
  4. 部分云厂商默认封锁 25 入站，需在安全组放行。
  5. 更完整的参数/错误码/多语言示例见项目仓库内 API.md。

⁠Tags

Tag说明
latest最新稳定
20260724按日期固定版本

Tag summary

Content type

Image

Digest

sha256:3fa261c3f…

Size

9 MB

Last updated

3 months ago

docker pull jjyy225/tmpemail