M
diggermail
v1.0.0 · GoldDigger

邮件营销工具 · 跑在客户自己的环境里

名单、模板、发送记录、统计全部留在客户本地的 SQLite 里。我们提供工具与实施:不售 token、不代理挖客、不代发信、不转售发送额度。

下载 diggermail-v1.0.0.zip 安装步骤 DNS 配置 能力边界
zip … 76796 bytes md5 e33f4e31b1d1dc8b70593fc5fd778e28 sha256 d647e756…935cb96a Python 3.9+ · 零第三方依赖
先读这一段 · 验收口径

多租户 = 单实例多域名多通道,不是 SaaS 级租户隔离

一个发信域名 = 一份 provider 事实 + 一套凭据文件 + 一条发送通道。SPF include、DKIM selector、发件人、凭据、预热桶全部按域名独立,互不影响。

它不是 SaaS 级的租户隔离:没有按租户分区的鉴权、没有数据分区、没有计费与配额隔离。同一实例里的所有域名共用同一个 API Key、同一个 SQLite、同一个运维与数据边界。

按 SaaS 的预期验收会出事。请按「单实例多域名多通道」验收。

能力概览
名单与模板
订阅者 / 名单分离
按邮箱 upsert,最小模板渲染
发送
SMTP / Relay / Mock
通道是客户自己的,我们不代发
限速
50 / 100 / 300 / 800 / 1500
按域名按日聚合,引擎强制
统计
幂等键防重复计数
续跑不会重发已投递的收件人
DNS
SPF / DKIM / DMARC
零依赖 DNS 客户端,按 record type 过滤
接口
预留 API + CLI
自带 Key 鉴权与审计
安装

解压即用,无需 pip install

包内含完整源码、INSTALL.txt 安装说明、客户版 DNS 文档与 111 个可复跑的用例。解压后所有命令都在包内目录里跑。

unzip diggermail-v1.0.0.zip
cd diggermail

python3 -m app.cli --help          # 命令行入口
python3 -m app.cli doctor          # 自检:能不能开 API
python3 -m app.cli demo --mock     # 走一遍 联系人→名单→campaign→发送
python3 -m unittest discover -s tests -t .   # 全量用例

第一次配置

export DIGGERMAIL_DATA_DIR=/var/lib/diggermail
python3 -m app.cli doctor 2>/dev/null || python3 -m app.cli keygen

# 登记发送通道:密钥只走环境变量,不进命令行、不进数据库
export MY_SMTP_PASSWORD=...
python3 -m app.cli sender add --domain mail.example.com --type smtp \
    --host smtp.your-provider.net --port 587 --starttls \
    --username your-account --password-env MY_SMTP_PASSWORD \
    --from-email sales@mail.example.com

# 写下这个域名自己的 provider 事实
python3 -m app.cli domain set --domain mail.example.com \
    --provider <你的邮件服务商> \
    --spf-include include:<服务商给你的 include> \
    --dkim-selector <服务商给你的 selector> \
    --from-email sales@mail.example.com

python3 -m app.cli serve          # 预留 API,默认 127.0.0.1:8742

凭据落在 <数据目录>/credentials/sender-<id>.json(权限 0600,仅本人可读);数据库里只留一条引用,不存密钥。

DNS

SPF / DKIM / DMARC 三项要过

SPF 里 include 谁、DKIM 用哪个 selector,都由客户自己的邮件服务商给出 —— 工具不写死任何一家。校验器只读公开 DNS,不发信、不碰凭据。

python3 -m app.cli dns-check --domain mail.example.com
python3 scripts/dm_deliverability.py dns-check --domain mail.example.com
退出码含义该做什么
0三项全过可以发信
1有记录没过改 DNS 配置(记录还没发布,或没告诉我们 selector)
2DNS 没查通查网络 —— 本机到 DNS 服务器不通,记录本身没问题

「查不到」不会报成「校验没过」。DNS 查不通时退出码是 2,输出里会写明哪几项没查成;那是环境问题,去查网络,别去动 DNS 记录。

DKIM selector 是服务商给的随机后缀(腾讯企业邮 / SES 常见形如 qcloudhk2048),工具猜不出来。查不到时它会明确提示「请提供 selector」,而不是断言「你没有 DKIM」。

python3 -m app.cli dns-check --domain golddigger.gold
[   PASS] SPF   one SPF record found
[   FAIL] DKIM  no DKIM key found for the common selectors — this domain may
          publish its DKIM key under a provider-issued selector (for example
          qcloudhk2048) — pass --selector <selector> ...
[   PASS] DMARC DMARC policy p=none (monitor only ...)
verdict: FAIL — fix the records above, then re-run

python3 -m app.cli dns-check --domain golddigger.gold --selector qcloudhk2048
[   PASS] SPF   one SPF record found
[   PASS] DKIM  DKIM public key published as a TXT record
[   PASS] DMARC DMARC policy p=none (monitor only ...)
verdict: PASS — SPF, DKIM and DMARC are all in place

完整的记录怎么填,见包内 docs/dns-records.md。

多域名

一个实例管多个发信域名

每个域名各登记一次通道、各写一次 provider 事实,然后发信时指定域名:

python3 -m app.cli domain check --domain a.example   # 用该域名自己的 selector / include 现场核
python3 -m app.cli demo --domain a.example --mock    # 这封信走 a.example 自己的通道
预留 API

接口清单

鉴权用工具自己的 Key(Authorization: Bearer 或 X-API-KEY,scope 默认 mail)—— 与云端 diggerkit 的 Key 是两套,互不通用。默认只听 127.0.0.1:8742。

接口说明
POST /api/v1/contacts新增 / 更新联系人(按邮箱 upsert)
POST /api/v1/lists/{id}/add名单批量导入(自动去重)
POST /api/v1/campaigns创建营销任务(draft 状态)
POST /api/v1/campaigns/{id}/senddraft / paused → running,触发发送
GET /api/v1/campaigns/{id}/stats送达 / 打开 / 点击 / 失败明细
GET /api/v1/lists名单列表(含成员数;?name= 精确查一个)
GET /api/v1/lists/{id}/members某个名单上都有谁
GET /api/v1/campaignscampaign 摘要(已发过哪些、状态、用的哪个域名)
GET /api/v1/domains域名 DNS 校验状态 + 预热进度(?check=1 现场查一次并落库)
POST /api/v1/domains写该域名的 provider / SPF include / DKIM selector / 发件人
GET /api/v1/senders列出各域名的发送通道(不返回任何凭据)
POST /api/v1/senders登记某域名的发送通道(凭据写入本地文件,不入库)
边界

能力边界(请一起验收)

工具边界
只提供工具与实施
不售 token、不代理挖客、不代发信、不转售发送额度
发送通道
客户自己的
客户自己的 MTA 或客户自选的邮件服务商;凭据只存在客户机器上
DNS 校验器
零第三方依赖
纯标准库实现,只读公开 DNS
干跑
--mock 绝不触网
短路点在通道选择层,用例断言真实上游调用数 == 0
尚未实现
开放 / 点击 webhook
统计口径与幂等键已就绪,缺触发源 —— stats 目前靠调用方写入
尚未实现
分布式频控 / 管理面板
频控是单进程内存计数;尚无 Vue 面板,命令行与 API 是当前界面

另外说明

包内容

解压后有什么

路径内容
app/主程序 12 个模块 + upgrade 自升级引擎
scripts/dm_deliverability.py可独立跑的 DNS 校验入口
docs/dns-records.md发信域 DNS 配置(客户版)
README.md / INSTALL.txt / VERSION说明、安装步骤、版本号
tests/111 个用例(含真起 HTTP 服务器、真实 socket SMTP 端到端、多租户双通道、真起 CLI 进程、mock 断网守卫)
GoldDigger · diggermail v1.0.0 · 下载地址 https://golddigger.gold/static/diggermail-v1.0.0.zip
工具只提供工具与实施,不售 token、不代理挖客、不代发信、不转售发送额度。