API 参考

邮件与会话

发送、获取、搜索、回复邮件，并查看投递事件。

筛选邮件与会话接口

POST/emails

API 密钥

发送一封邮件

从工作区的已验证域名发送事务性的 HTML、纯文本或托管模板内容。如果已为该已验证的发信域名启用营销邮件，直接发送时可以将 message_class 设为 marketing。营销邮件会自动添加托管的退订邮件头，除非已配置的第一方集成提供了自己的可见 HTTPS 一键退订 URL。

可选请求头Idempotency-Key

请求

curl https://sendhq.cc/api/v1/emails \
  -X POST \
  -H "Authorization: Bearer $SENDHQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"from":"Acme <hello@example.com>","to":["customer@example.net"],"subject":"Welcome aboard","html":"<h1>Welcome</h1><p>Your workspace is ready.</p>","text":"Welcome. Your workspace is ready."}'

201 响应

{
  "id": "em_…",
  "providerMessageId": "provider-id",
  "threadId": "em_…"
}

POST/emails/batch

API 密钥

发送最多 100 封个性化邮件

可选请求头Idempotency-Key

请求

curl https://sendhq.cc/api/v1/emails/batch \
  -X POST \
  -H "Authorization: Bearer $SENDHQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"emails":[{"from":"Acme <hello@example.com>","to":["customer@example.net"],"subject":"Welcome aboard","html":"<h1>Welcome</h1><p>Your workspace is ready.</p>","text":"Welcome. Your workspace is ready."}]}'

201 响应

{
  "data": [
    {
      "index": 0,
      "ok": true,
      "id": "em_…"
    }
  ],
  "count": 1,
  "successful": 1,
  "failed": 0
}

GET/emails

API 密钥

列出已发送和已收到的邮件

按从新到旧排列的列表，支持筛选。`query` 会搜索主题、正文、参与者和附件文件名。`label`、`domain` 和 `category` 接受单个值或逗号分隔的列表（匹配其中任意一个）；标签可以是 ID 或名称。`archived=false` 返回收到邮件的收件箱视图。收到的邮件会被分类为 `primary`、`updates`（新闻通讯、群发和自动发送的邮件）或 `spam`，并可被标记为 `important`；除非指定 `category=spam` 或 `include_spam=true`，否则垃圾邮件不会包含在结果中。

查询参数directionstatusdomaininbox_idlabelarchivedcategoryimportantinclude_spamfromtounreadafterbeforequerylimitoffset

请求

curl https://sendhq.cc/api/v1/emails \
  -X GET \
  -H "Authorization: Bearer $SENDHQ_API_KEY"

200 响应

{
  "data": [],
  "count": 0
}

GET/emails/:id

API 密钥

获取邮件及其附件

请求

curl https://sendhq.cc/api/v1/emails/id_value \
  -X GET \
  -H "Authorization: Bearer $SENDHQ_API_KEY"

200 响应

{
  "id": "em_…",
  "direction": "out",
  "status": "sent",
  "attachments": []
}

PATCH/emails/:id

API 密钥

更新已读、归档、垃圾邮件、分类或重要性状态

设置 `read`、`archived`、`category`（`primary`、`updates` 或 `spam`，仅限收到的邮件）和 `important`。更改 `category` 或 `important` 会让 SendHQ 学习该发件人的情况：被举报为垃圾邮件后，该发件人今后的邮件都会进入垃圾邮件；标记为“Not spam”会让其邮件跳过自动垃圾邮件检查；重要性标记也会沿用到该发件人。传入 `learn: false` 则只更改这一封邮件。

请求

curl https://sendhq.cc/api/v1/emails/id_value \
  -X PATCH \
  -H "Authorization: Bearer $SENDHQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"category":"spam"}'

200 响应

{
  "id": "em_…",
  "readAt": "2026-08-23T12:00:00.000Z",
  "archivedAt": null,
  "category": "spam",
  "important": false,
  "classification": "you moved it here"
}

DELETE/emails/:id

API 密钥

删除已保留的邮件

请求

curl https://sendhq.cc/api/v1/emails/id_value \
  -X DELETE \
  -H "Authorization: Bearer $SENDHQ_API_KEY"

200 响应

{
  "ok": true
}

GET/emails/:id/events

API 密钥

列出某封邮件的投递事件

请求

curl https://sendhq.cc/api/v1/emails/id_value/events \
  -X GET \
  -H "Authorization: Bearer $SENDHQ_API_KEY"

200 响应

{
  "data": [],
  "count": 0
}

GET/threads/:id

API 密钥

按时间顺序获取一个会话

请求

curl https://sendhq.cc/api/v1/threads/id_value \
  -X GET \
  -H "Authorization: Bearer $SENDHQ_API_KEY"

200 响应

{
  "id": "em_…",
  "data": [],
  "count": 0
}