以买邮开放 API

把整条邮件推广链路开成接口：注册、加发件箱、批量导入联系人、群发、单发、查进度、搜邮件。 只需要 HTTP 请求，AI Agent 就能从头跑到尾；其他系统也可以把「发邮件」当成一个函数来调。

Base URL：https://api.hzhigzho.cn/api/v1

所有响应统一为 {"code":0,"message":"success","data":{…}}，code 为 0 表示成功。

5 分钟接入

下面五步就是一次完整的推广，复制即可运行。把 $TOKEN 换成上一步返回的 token。

# 1) 注册，直接拿到长期 token
curl -X POST https://api.hzhigzho.cn/api/v1/agent/register \
  -H 'Content-Type: application/json' \
  -d '{"username":"my-ai-agent","password":"a-strong-password"}'

# 2) 加发件箱：只给邮箱 + 授权码，服务器地址自动识别
curl -X POST https://api.hzhigzho.cn/api/v1/agent/senders \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"email":"you@qq.com","auth_code":"邮箱授权码","from_name":"张三"}'

# 3) 导联系人：一次传几万个，超过 800 人自动切成 分组1 / 分组2…
curl -X POST https://api.hzhigzho.cn/api/v1/agent/contacts \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"emails":["a@example.com","b@example.com"],"group_size":800}'

# 4) 群发（默认立即开始）
curl -X POST https://api.hzhigzho.cn/api/v1/agent/broadcast \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"subject":"A-1200 报价单","content":"您好，附件是我们的报价…","categories":["分组1","分组2"]}'

# 5) 查进度
curl https://api.hzhigzho.cn/api/v1/agent/tasks/<campaign_id> \
  -H "Authorization: Bearer $TOKEN"

认证方式

两种凭证等价，业务接口完全一样：

• JWT：注册 / 登录接口直接返回，放在 Authorization: Bearer <token>。有效期很长，适合一次性接入。
• API Key：以 mmk_ 开头，可以随时吊销、独立计数，适合长期交给 AI 或第三方系统。支持 Authorization: Bearer mmk_xxx 或 X-API-Key: mmk_xxx。

GET 请求也可以把凭证放在 ?token= 里，方便浏览器直接打开链接。

账号

参数	类型	说明
username 必填	string	邮箱 / 手机号 / 英文数字下划线，注册后即账号
password 必填	string	至少 6 位

{"code":0,"message":"success","data":{"token":"eyJhbGciOi…","user":{…}}}

curl -X POST $API/agent/login -H 'Content-Type: application/json' \
  -d '{"username":"my-ai-agent","password":"a-strong-password"}'

返回发件箱数量、联系人数、分组列表、最近任务，以及 next_steps——下一步该做什么写得很直白，模型可以直接照着执行。

{
  "username": "my-ai-agent",
  "max_senders": 1,            // 0 表示不限
  "sender_count": 1,
  "contact_total": 1600,
  "categories": [{"id":"…","name":"分组1"},{"id":"…","name":"分组2"}],
  "next_steps": ["可以群发了：POST /agent/broadcast …"]
}

发件箱

不需要知道 SMTP 服务器地址。内置 QQ、163、126、Gmail、Outlook、iCloud、阿里企业邮、腾讯企业邮等常见服务商；自有域名会查 MX 记录判断托管商（腾讯 / 阿里 / 网易 / Google / Microsoft），再不行才按 smtp.域名 猜测。

不需要登录。返回该邮箱应该用的 SMTP / IMAP 地址与端口，以及服务商提示（比如「QQ 邮箱需使用授权码」）。

参数	类型	说明
email 必填	string	发件邮箱地址
auth_code 必填	string	邮箱授权码 / 应用专用密码（也接受 password 字段）
from_name	string	发件人显示名
daily_limit	int	该账号每日发信上限，0 表示按默认
smtp_host / smtp_port	string / int	可选。不传就走自动识别；识别不准时用来覆盖
imap_enabled	bool	是否开启收信同步，默认 true

{"email":"you@qq.com","auth_code":"abcdefghijklmn"}

{"code":0,"data":{"id":"…","smtp":"smtp.qq.com:465","imap":"imap.qq.com:993",
 "detected_from":"preset","preset":{"provider":"QQ 邮箱","source":"preset"}}}

联系人

一个分组默认装 800 人。传进来 1600 个人，会自动创建「分组1」「分组2」；如果指定了 category，则命名为「客户A-分组1」「客户A-分组2」。重复导入的邮箱不会重复建，只会被移动到新分组。

参数	类型	说明
emails	string[]	邮箱数组。与 text 二选一或同时传
text	string	整块文本，支持换行 / 逗号 / 分号 / 空格 / 制表符分隔
category	string	分组名。为空则用「分组1、分组2…」
group_size	int	每组人数，默认 800，上限 5000；传 -1 表示不拆分

curl -X POST $API/agent/contacts -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"emails":["lead1@example.com","lead2@example.com"],"category":"客户A"}'

# 返回
{"input":1600,"inserted":1600,"updated":0,"skipped":0,
 "groups":[{"category_id":"…","name":"客户A-分组1","count":800},
           {"category_id":"…","name":"客户A-分组2","count":800}]}

按邮箱、姓名、公司、电话模糊匹配，返回精简字段，避免把整个联系人表塞进上下文。

发邮件

参数	类型	说明
to 必填	string	收件人，多个用逗号分隔
subject	string	主题，为空时用「您好」
content 必填	string	正文。纯文本会自动按换行转成 HTML
html	bool	为 true 时 content 按 HTML 原样发送
signature	string	签名
from	string	指定用哪个发件箱，不传则由邮箱池轮询

curl -X POST $API/agent/send -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"to":"buyer@example.com","subject":"回复：报价","content":"您好，报价单见附件。"}'

参数	类型	说明
subject 必填	string	邮件主题
content 必填	string	正文，纯文本自动转 HTML
categories	string[]	按分组名指定收件人，例如 ["分组1","分组2"]
category_ids	string[]	按分组 id 指定，二选一
emails	string[]	直接给一批邮箱，会自动落进「API 快速群发」分组
start	bool	默认 true 立即开始；传 false 只建草稿
batch_size	int	每批人数，1 为一封一封发，>1 用密送，最大 100
send_interval	int	每批间隔秒数，0 用全局默认
html	bool	正文是否为 HTML
name	string	任务名，不传自动用「主题 + 时间」

{"code":0,"data":{"campaign_id":"6aea…","status":"running","recipient_count":1600,
 "next":"GET /agent/tasks/6aea… 查进度（sent / failed / opened / clicked）"}}

任务进度

{"status":"running","recipient_count":1600,"progress":"42%",
 "stats":{"total":1600,"sent":672,"success":669,"failed":3,"bounced":0,"opened":184,"clicked":37}}

status 取值：draft 草稿、running 发送中、paused 已暂停、completed 已完成、failed 失败。

搜索

关键词匹配主题、发件人、正文；再传 email 就只看跟某个人的往来。返回正文截断到 400 字，刚好够模型判断内容又不撑爆上下文。

{"total":1,"items":[{"from":"buyer@example.com","subject":"RE: 关于 A-1200 的报价",
 "text":"请再给我一份正式报价单，我们采购 500 台…","received_at":"2026-11-04T02:30:04Z",
 "is_read":false,"attachments":0}]}

API Key

curl -X POST $API/agent/keys -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' -d '{"name":"cursor-agent"}'

# 返回（明文只出现这一次）
{"id":"…","prefix":"mmk_c405929c","api_key":"mmk_c40592…"}

错误码与限制

code	含义	怎么处理
0	成功	—
400	参数错误	看 message，通常会直接说明缺什么
401	未登录 / 凭证无效	重新登录或换一个 API Key
403	账号被封禁	联系管理员解封
404	资源不存在	确认 id 属于当前账号
500	服务端异常	可重试一次；持续失败请联系我们

• 发件箱数量按账号配额限制，默认 1 个，需要更多联系 mark@highzo.com。
• 每个发件箱可单独设 daily_limit，多账号轮询会自动分摊，降低进垃圾箱与封号风险。
• 单个分组默认 800 人，单次导入建议不超过 20 万个邮箱，超出请分批。

给 AI 的接入说明

如果你要把这套能力交给模型，只要给它两个地址就够了：

• https://www.hzhigzho.cn/docs/openapi.json：机器可读的接口定义
• https://www.hzhigzho.cn/llms.txt：产品与接口的纯文本摘要

推荐的任务顺序（每一步都能单独重试，接口是幂等的）：

GET  /agent/me                       // 先看家底，缺什么补什么
POST /agent/senders                  // 有邮箱 + 授权码就能发
POST /agent/contacts                 // 几万个邮箱自动分组
POST /agent/broadcast {"start":false} // 先建草稿核对
POST /agent/tasks/:id/start          // 确认后再真正发出
GET  /agent/tasks/:id                // 轮询进度
GET  /agent/messages/search          // 有人回信就去读、去跟进