面向 AI 智能体

SendHQ MCP 服务器

Give an AI agent full, safe control of one SendHQ workspace: send and receive email, verify domains, publish templates, and investigate deliverability through 142 strictly typed tools. Written for agents first; humans welcome.

142 toolsstdio transport, one command0 key-management tools
安装并连接(Claude Code)
curl -fsSL https://downloads.sendhq.cc/install.sh | sh
claude mcp add sendhq --env SENDHQ_API_KEY=re_your_key -- sendhq mcp

这个服务器是什么

The SendHQ MCP server lets an AI agent operate one SendHQ workspace through the Model Context Protocol: send email (single, batch, templated, replies, attachments, idempotent retries), read and search sent and received mail (subjects, bodies, and attachment names) and its delivery events, organize mail into labels with auto-filing rules, manage drafts and private attachments, author and publish hosted templates, add and verify domains and their DNS, set up inbound receiving and inbound addresses, inspect deliverability, bounces, complaints, and suppressions, run newsletters (consented contacts with tags and custom fields, segments, lists with signup forms, welcome emails, and newsletter sites, and broadcasts with pre-send checks, test sends, scheduling, and bot-filtered open and click reports), and read account usage, billing state, analytics, and API-key metadata.

它是一个内置在 sendhq CLI 二进制文件中的本地 stdio 服务器。您的 MCP 客户端会以子进程方式启动 sendhq mcp,并通过 stdin/stdout 使用 JSON-RPC 通信。每一次工具调用都会变成一个对 https://sendhq.cc/api/v1 上 SendHQ REST API 的有文档记录的请求,并使用您的工作区 API 密钥进行身份验证,因此 MCP 服务器拥有的权限与该密钥完全一致,不多也不少。

  • 142 tools in 10 groups, generated from one catalog that is also published as tools.json.
  • 严格的 JSON Schema:未知参数、类型错误和缺少必填字段都会在本地被拒绝,不会有任何请求到达 SendHQ。
  • 结构化错误,包含稳定的 code、HTTP status、explanation(说明)、具体的 remedy(补救措施),以及重试是否有帮助。
  • 每个会发送真实邮件或销毁数据的工具,都会在其描述的开头明确说明,并带有 MCP 安全注解。
  • --read-only 模式会隐藏所有发送类和修改类工具。
  • 不记录任何日志。stdout 只传输协议消息;API 密钥和邮件内容永远不会进入日志。
这不是文档 MCP 端点。SendHQ 还在 https://sendhq.cc/api/mcp 托管了一个小型只读文档 MCP 端点(用于查询价格和文档,不能访问账户)。本页介绍的是完整的、限定在账户范围内的服务器;它可以在本地运行,也可以作为下文的托管连接器使用。

Use SendHQ in Claude, ChatGPT and Grok

无需安装:SendHQ 还在 https://mcp.sendhq.cc/mcp 以托管连接器的形式运行此服务器,工具完全相同。您只需使用 SendHQ 账户登录,无需粘贴密钥。

Claude

  1. 打开 Settings → Connectors,在目录中找到 SendHQ;或选择 Add custom connector 并粘贴 https://mcp.sendhq.cc/mcp。
  2. 点击 Connect,登录 SendHQ,查看授权范围后点击 Allow。
  3. 让 Claude 查看您的收件箱、从您的已验证域名发送邮件,或解释某次退信的原因。

ChatGPT

  1. Open Settings → Security and login and turn on Developer mode.
  2. Go to chatgpt.com/plugins, click Create MCP app, name it SendHQ and enter https://mcp.sendhq.cc/mcp.
  3. Sign in to SendHQ and click Allow, then pick SendHQ from the tools menu in a new chat.

Grok

  1. Go to grok.com/connectors, click New Connector, then Custom.
  2. Enter https://mcp.sendhq.cc/mcp, sign in to SendHQ and click Allow.

Muse by Meta

In Muse, open Connectors and search for SendHQ. Click Connect, sign in to SendHQ and click Allow.

审批与断开连接

  • The request_feature tool sends a feature request to the SendHQ team with your account details, so we can follow up by email.
  • 会发送真实邮件或删除数据的工具都有明确标注。助手是否先征求您的同意,需要在助手中按工具分别设置:在 Claude 中,前往 Settings → Connectors → SendHQ,为这些工具选择 Needs approval。
  • 连接器会获得一个独立的 API 密钥,并以助手命名(例如“Claude (AI connector)”)。在 API Keys 中删除该密钥即可立即断开连接。
  • 它不能创建或吊销 API 密钥,也不能更改计费设置。附件以 base64 形式发送和返回;它无法访问本地文件。
  • Sending requires an active subscription. There is no free allowance, including mail to the account owner.

如有疑问:postmaster@sendhq.cc。隐私政策:sendhq.cc/privacy。

安装

安装 sendhq 二进制文件(支持 x86-64 和 arm64 上的 Linux、macOS 和 Windows)。安装程序会校验发布版本的校验和,并默认将二进制文件放到 ~/.local/bin。

macOS 和 Linux
curl -fsSL https://downloads.sendhq.cc/install.sh | sh
Windows PowerShell
irm https://downloads.sendhq.cc/install.ps1 | iex
检查安装结果
sendhq version
SENDHQ_API_KEY=re_your_key sendhq doctor

在控制台的 https://sendhq.cc/app#/keys 创建 API 密钥。MCP 服务器无法创建密钥。运行服务器只需要这一条命令:

运行 stdio 服务器
SENDHQ_API_KEY=re_your_key sendhq mcp

通常您不需要手动运行它:MCP 客户端会负责启动。在终端中运行时,它会等待 stdin 上的 JSON-RPC 输入。

配置您的客户端

Claude Code

claude mcp add
claude mcp add sendhq --env SENDHQ_API_KEY=re_your_key -- sendhq mcp

# read-only variant
claude mcp add sendhq-readonly --env SENDHQ_API_KEY=re_your_key -- sendhq mcp --read-only

添加 --scope user 可使其在所有项目中可用,添加 --scope project 则会将其写入项目的 .mcp.json。对于共享的 .mcp.json,请从环境变量中引用密钥,而不是将其提交到代码库;Claude Code 会展开 .mcp.json 中的 ${VAR}。

.mcp.json
{
  "mcpServers": {
    "sendhq": {
      "command": "sendhq",
      "args": [
        "mcp"
      ],
      "env": {
        "SENDHQ_API_KEY": "${SENDHQ_API_KEY}"
      }
    }
  }
}

OpenAI Codex

~/.codex/config.toml
[mcp_servers.sendhq]
command = "sendhq"
args = ["mcp"]
env = { SENDHQ_API_KEY = "re_your_key" }

也可以通过命令行添加:codex mcp add sendhq --env SENDHQ_API_KEY=re_your_key -- sendhq mcp。

Claude Desktop

编辑 claude_desktop_config.json(macOS:~/Library/Application Support/Claude/,Windows:%APPDATA%\Claude\),然后重启应用。桌面应用不会继承 shell 的 PATH,因此请使用二进制文件的绝对路径(which sendhq)。

claude_desktop_config.json
{
  "mcpServers": {
    "sendhq": {
      "command": "/Users/you/.local/bin/sendhq",
      "args": [
        "mcp"
      ],
      "env": {
        "SENDHQ_API_KEY": "re_your_key"
      }
    }
  }
}

其他任何 MCP 客户端

将 stdio 服务器配置为:命令 sendhq,参数 ["mcp"](可选加上 "--read-only"),并设置下面的环境变量。该服务器支持 MCP 协议版本 2024-11-05、2025-03-26、2025-06-18 和 2025-11-25,并实现了 initialize、ping、tools/list 和 tools/call。工具结果同时包含一个 JSON 文本块和 structuredContent。

原始 stdio 冒烟测试(通过管道输入 sendhq mcp)
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"probe","version":"1"}}}
{"jsonrpc":"2.0","method":"notifications/initialized"}
{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"get_service_health","arguments":{}}}

限定在账户范围内的服务器没有托管的 HTTP 传输方式。一个远程、可写的 MCP 端点需要按用户进行 OAuth 授权,而 SendHQ 并不提供;本地二进制文件则让密钥始终留在本就持有它的机器上。

环境变量与命令行参数

变量或参数必填含义
SENDHQ_API_KEY是工作区 API 密钥(re_…)。除 get_service_health 外的每个工具都需要它。没有它,服务器仍会启动,但每次调用都会返回一个结构化的 auth_error,说明如何修复。
SENDHQ_API_BASE_URL否API base URL。默认值为 https://sendhq.cc/api/v1。仅在本地或预发布部署中使用。SENDHQ_BASE_URL 作为旧的别名仍被接受。
SENDHQ_MCP_READ_ONLY否1、true 或 yes 的效果与 --read-only 相同。
--read-only否只暴露既不发送邮件也不改变状态的工具。被隐藏的工具即使按名称调用也会被拒绝。
SENDHQ_PROFILE / --profile否使用 sendhq auth login 存储在操作系统密钥环中的密钥,而不是 SENDHQ_API_KEY。两者同时存在时,以环境变量为准。

密钥只会作为 Authorization: Bearer 请求头发送到配置的 base URL。它永远不会被打印、记录到日志、在错误中回显,或包含在工具结果中。

面向智能体的安全模型

  • Sends real email. send_email, send_batch, send_template_test, send_broadcast, send_broadcast_test, schedule_broadcast (at the scheduled time), and send_broadcast_to_more deliver mail to real people and consume delivery credits. Their descriptions start with SENDS REAL EMAIL. Call them only when the user explicitly asked for that specific message to be sent, with the recipients, sender, and content confirmed.
  • Destructive. delete_email, delete_draft, delete_attachment, delete_domain, delete_inbox, remove_suppression, the campaign deletes (delete_contact, delete_list, remove_list_contact, delete_broadcast, cancel_broadcast, delete_segment, delete_contact_field), and bulk_update_contacts are marked destructiveHint: true and their descriptions start with DESTRUCTIVE. Confirm with the user first. remove_suppression weakens a safety block and is appropriate only when a human confirms the address works again.
  • 改变状态。创建或更新草稿、模板、域名和收件箱,发布模板,以及发起验证,都会改变工作区状态,但不会发送邮件。
  • 只读。其余所有工具都是 readOnlyHint: true,可以放心随意调用。
  • 此服务器从不修改 DNS。add_domain 返回需要由人工发布的记录;get_domain_connect_link 返回一个授权 URL,必须由人打开并在其 DNS 服务商处批准。
  • 此服务器从不修改计费设置。get_account 只读取套餐、用量和订阅状态。
  • Sending requires an active subscription. There is no free allowance. Every send, including a test and a send to the account owner's own address, returns subscription_required (402) until a plan is active. Lapsed, cancelled, and past-due subscriptions are refused the same way. The owner chooses a plan in the dashboard (Profile & Billing) or at https://sendhq.cc/pricing. Unpaid workspaces can still verify domains, create keys, and read the workspace.
  • Accepted is not delivered. A successful send returns an ID; delivery, bounce, and complaint evidence arrives later in list_email_events. Never claim inbox placement or that a person read a message. Broadcast opens are estimates: privacy proxies and security scanners load images on their own, and requests that look automated are counted apart (machine in get_broadcast_report).
  • 不要为了绕过 423 暂停而换用其他 From 地址,也绝不要重新添加已退订或已投诉的收件人。

API 密钥不在范围之内

按照设计,没有任何工具可以创建、修改、轮换、吊销或删除 API 密钥。智能体不得生成或销毁凭据。list_api_keys 只返回名称、非机密的前缀和最近使用时间。密钥管理始终留在控制台中,由已登录的人来完成。

工作流

1. 首次发送

  1. get_service_health 确认 API 可以访问(无需密钥即可使用)。
  2. get_account shows the plan (access.tier) and remaining quota. If there is no active plan, do not send: the call returns subscription_required.
  3. list_sending_identities 列出您可以使用的 From 地址。如果列表为空,请先完成域名工作流。
  4. 与用户确认发件人、收件人、主题和正文,然后带上 idempotency_key 调用 send_email。
  5. 一旦服务商上报结果(通常在几秒到几分钟内),使用返回的 id 调用 list_email_events,即可看到 delivery、bounce、complaint 或 reject。
首次发送
{
  "name": "send_email",
  "arguments": {
    "from": "Acme <hello@example.com>",
    "to": [
      "owner@example.com"
    ],
    "subject": "SendHQ is connected",
    "text": "It works.",
    "idempotency_key": "first-send-2026-09-26"
  }
}

2. 端到端的域名验证

  1. add_domain with name: "example.com". The result includes the DNS records (DKIM CNAMEs, domain verification, SPF, recommended DMARC).
  2. 使用 domain_id 调用 get_dns_provider,会检测权威 DNS 服务商,并返回在该服务商处每条记录应填写的准确相对主机名。
  3. If providers.domainConnect.available is true, get_domain_connect_link returns a consent URL. Give it to the human; nothing changes until they approve at the provider. Otherwise, give the human the records to publish. Never publish a second SPF record: merge SendHQ's SPF include (include:amazonses.com) into the existing v=spf1 value.
  4. verify_domain rechecks DNS and DKIM verification. Status moves through pending, checking, and propagating to verified. Poll verify_domain or get_domain every 30–60 seconds; DNS can take minutes to hours.
  5. 当 status 为 verified 时,该域名的地址会出现在 list_sending_identities 中。

3. 退信、投诉和抑制记录

  1. list_blocked_recipients 返回每个被拦截的地址及其原因(bounce、complaint、unsubscribe),以及汇总计数。
  2. list_suppressions 返回硬退信和投诉类抑制记录;deliverability_stats 提供 30 天的投递率、退信率和投诉率;list_sender_reputation 显示哪些 From 地址被限流或暂停。
  3. 包含被抑制收件人的发送会以 422 recipient_suppressed 失败。请移除该收件人后重新发送。
  4. 只有在人工确认某个退信邮箱已恢复正常时,才调用 remove_suppression。投诉类抑制是永久性的(409 complaint_suppression_locked)。

4. 接收入站邮件

  1. 该域名(通常是子域名,例如 inbound.example.com)必须已通过验证。
  2. setup_inbound 会开通收信功能,并返回一条 MX 记录,由人工发布。
  3. 反复调用 verify_inbound,直到 status 变为 ready。
  4. 使用 domain_id 和 local_part(例如 support)调用 create_inbox,即可创建 support@inbound.example.com。
  5. 使用 direction: "in" 和 unread: true(可选加上 inbox_id)轮询 list_emails。使用 get_email 读取邮件,使用 get_thread 读取其会话,使用 download_attachment 下载附件,并使用 mark_email(read: true)将其标记为已处理。
  6. 使用 send_email 并带上 reply_to_email_id 在会话中回复;SendHQ 会设置 In-Reply-To、References 和会话。

5. Webhook 与事件通知

Webhooks push signed events to an endpoint a human configures in the dashboard or with the REST API (see /docs/webhooks): email events (email.sent, email.delivered, email.delivery_delayed, email.bounced, email.complained, email.failed, email.received), contact.unsubscribed when a recipient unsubscribes from a marketing or automation email, and, for automations, automation.entered, automation.converted, and automation.exited. There is no webhook tool, because endpoint responses carry signing secrets. An agent without a webhook polls instead: list_email_events for one message's outcome, list_emails with status (for example bounced) or after for recent changes, list_emails with direction: "in" and unread: true for new inbound mail, and list_blocked_recipients for new suppressions. Poll no more than about once a minute per question.

6. 诊断投递失败

  1. 找到这封邮件:使用 direction: "out" 加上 to 或 query 调用 list_emails;如果您有 ID,则调用 get_email。status: failed 表示 SendHQ 或服务商在提交时拒绝了它;邮件的错误信息会说明原因。
  2. list_email_events:bounce(永久性或暂时性,附带服务商的诊断信息)、complaint、reject 或 delivery。如果还没有任何事件,说明服务商尚未上报;请稍后再查。
  3. If the send call itself failed, read the error code: subscription_required → the owner activates a plan; sender_domain_unverified → finish domain verification; recipient_suppressed → the address hard-bounced or complained before; sender_paused → inspect list_sender_reputation; account_paused → the workspace is paused for review, read the rates; daily_limit_reached → wait until midnight UTC; quota_exhausted → get_account usage.
  4. get_domain 检查 DKIM、SPF 和 DMARC 是否仍然已发布;deliverability_stats 显示问题只出在单封邮件上,还是一种趋势。
  5. 如实报告证据所显示的内容。delivery 事件表示收件人的服务器接受了邮件,并不表示邮件进入了收件箱或已被阅读。

7. 拥有自己的任务分类(标签)

  1. 使用 name(例如 Agent/Orders)和 skip_inbox: true 调用 create_label。这样该标签就成为一个分类:收到的邮件一旦获得该标签就会被归档,因此只会出现在该标签中,永远不会出现在人类用户的收件箱里。
  2. 使用 send_email(或 send_batch)并带上 labels: ["Agent/Orders"] 发送任务邮件。该会话的回复会自动继承该标签,并跳过收件箱。
  3. 对于并非起始于您的会话的邮件,请添加归档规则:使用 inbox_id(一个专用地址,例如 orders@…)、from、to 或 subject 调用 create_label_rule。传入 apply_to_existing: true 可同时归档已收到的邮件。
  4. 处理分类中的邮件:使用 label: "Agent/Orders"、direction: "in" 和 unread: true 调用 list_emails;使用 get_email 或 get_thread 读取,使用 send_email 并带上 reply_to_email_id 回复,处理完毕后调用 mark_email 并设置 read: true。
  5. 使用 label_email(add / remove)将放错位置的邮件移入或移出。为收到的邮件添加分类标签时,也会将其归档。
  6. 此外,还可以使用 set_inbox_forwarding 将某个收件地址收到的所有邮件抄送一份到另一个邮箱(目标邮箱需要先通过邮件确认)。
发送到分类
{
  "name": "send_email",
  "arguments": {
    "from": "Orders <orders@example.com>",
    "to": [
      "customer@example.net"
    ],
    "subject": "Order 1042: confirm delivery window",
    "text": "Reply with a time that works.",
    "labels": [
      "Agent/Orders"
    ],
    "idempotency_key": "order-1042-window"
  }
}

8. 附件与模板

在付费套餐下,可通过 send_email 的 attachments 最多附加 10 个文件(每个文件需要提供 content_base64 或本地 file_path;filename 默认为文件的基本名称)。托管模板的流程为:create_template → update_template_draft → render_template(使用示例数据预览)→ send_template_test(发送一封真实的测试邮件)→ publish_template,然后使用 send_email 或 send_batch,通过 template: {key, data} 并指定恰好一个 to 收件人进行发送。

9. Send a newsletter

  1. Audience: list_lists (or create_list with a signup form), and optionally preview_segment then create_segment to narrow it, for example to contacts tagged VIP who opened in the last 90 days. Add only people who asked for your email: every subscribed contact needs a consent_basis.
  2. get_newsletter_settings: if postalAddress is empty, ask the user for one and set it with update_newsletter_settings (marketing email needs it).
  3. create_broadcast with list_id, a verified from, subject, preview_text, content (markdown is simplest), and optionally audience (segment_id, limit, order: engaged).
  4. check_broadcast: fix every block item and tell the user about warn items. Then send_broadcast_test to the user's own address so they can look at it.
  5. Only when the user says to send: send_broadcast now (with an idempotency_key), or schedule_broadcast with scheduled_at (unschedule_broadcast to change it).
  6. Follow up with get_broadcast (delivery totals), get_broadcast_report (opens, clicks, links, inbox providers, against your average), and list_broadcast_recipients with activity. Report opens as estimates. With a limited audience, send_broadcast_to_more sends to the next people.
Draft a broadcast
{
  "name": "create_broadcast",
  "arguments": {
    "list_id": "lst_…",
    "from": "Acme <news@example.com>",
    "subject": "What shipped in October",
    "preview_text": "Three new features",
    "markdown": "Hi {{first_name | there}},\n\nHere is what shipped this month.",
    "audience": {
      "segment_id": "seg_…"
    }
  }
}

10. Run an automation

An automation is a timed sequence of emails that starts when a contact does something and stops when they convert. Automations are being enabled workspace by workspace: a workspace that is not enabled gets 403 automations_not_enabled from every tool below.

  1. create_automation with a key, the entry event, exit_rules (the goal_event that counts as converting, or no_goal: true), a verified from_address, and steps, each due offset_seconds after the person entered. It starts as a draft and sends nothing. Every automation carries domain, the domain of its from_address; in a workspace that sends from several domains, list_automations and get_automations_overview take domain to show the automations of one of them.
  2. To let the user read it first: send_automation_test_email sends one email, and send_automation_test every email in order, to the account's own address only (never to a contact), with stand-in values for the merge tags. A test enrols nobody, is in no report, and works while the automation is still a draft. Both send real email, so only when the user asks. send_automation_test_email with dry_run: true returns the rendered email without sending anything.
  3. get_sending_limits shows how much automation email one person may get across every automation, and during which hours. Change them with update_sending_limits only when the user asks.
  4. To start from a ready-made email instead of writing one: list_automation_templates is the template library (welcome, onboarding tips, a nudge to finish setup, trial ending and trial ended, abandoned checkout, failed payment or dunning, receipt, upgrade at a usage limit, feature announcement, review request, feedback score, cancellation survey, and winback for retention), get_automation_template shows one with the email as this workspace would send it, and use_automation_template makes the draft automation with the emails, the suggested entry event and the suggested goal. Some templates come as a set that makes one automation: three onboarding tips, trial ending then trial ended, payment failed then a last notice. set_automation_step with template loads one template into an email of an automation that already exists.
  5. An email can also be built in the dashboard's drag-and-drop builder. get_automation shows such an email with editor design: its content is the builder's project, which only the builder writes, and its html is what is sent. Leave the project alone. To change the wording of a designed email, ask the user to open it in the dashboard; to replace it, send your own html with editor html.
  6. A template is finished except for what only the user knows, written as placeholders in square brackets: [First step], or [Link to plans] as a link's address. to_fill on the automation lists each one by email, and each workspace name the emails print that is blank. Ask the user for the real words and links, write them in with set_automation_step, and set product_name and sender_name with update_sending_limits. Never invent them. set_automation_status refuses to turn the automation on while anything is left (422 automation_not_ready, with a problems list that names each email and detail); test emails are allowed, so the user can read it first.
  7. Only when the user says to start: set_automation_status with status: "on".
  8. Record what people do with track_event (a new contact needs contact.consent_basis). The entry event starts the sequence, the goal event ends it as converted, and a dedupe_key makes a retry harmless. enroll_contact and exit_contact add or remove one person by hand.
  9. preview_automation shows, for everyone in the automation now, which email would go out if they were evaluated at this moment, or why not: nothing due until a time, held by a limit or the sending hours until a time, waiting behind a higher-priority automation, or skipped. It sends nothing and changes nothing.
  10. list_automations gives each automation's 30-day totals. An email that a limit holds back is not dropped: it goes out when the limit allows. When several emails of one automation are due at once, only the latest is sent.
  11. Results: get_automations_overview (every automation) and get_automation_report (one automation, with a row per email) give totals and a number for each day of a date range: people who entered, emails sent, delivered, opened, clicked, and converted. list_automation_people lists who did what (did: entered, sent, delivered, opened, clicked, converted, bounced, unsubscribed, or waiting), and get_automation_person gives one contact's history with every open and click. Automation emails are tracked like broadcasts: report opens and clicks as estimates, and note that automated requests are labelled machine and never counted.
Start from a template
{
  "name": "use_automation_template",
  "arguments": {
    "template_id": "payment-failed-notices",
    "from_name": "Dana from Acme",
    "from_address": "dana@example.com"
  }
}
Dry run
{
  "name": "preview_automation",
  "arguments": {
    "automation_key": "checkout-recovery"
  }
}
Who clicked the first email
{
  "name": "list_automation_people",
  "arguments": {
    "automation_key": "checkout-recovery",
    "did": "clicked",
    "step": 1
  }
}

11. See what came in, and connect another system

Events reach SendHQ three ways: track_event from the workspace's own code, a connection (a secret address a payment provider or another system posts its webhooks to), and a spreadsheet uploaded in the dashboard. See /docs/events.

  1. list_events is the feed of everything recorded, newest first: who, what they did (also as plain words), when, where it came from, and which automations it started, ended, or converted. Filter by contact, by name, or by date. list_event_names lists the kinds of event seen in the last 30 days.
  2. list_connections shows each connection with its last delivery in plain words, and get_connection its last 50 deliveries: "Recorded 2 events", "Skipped: no email address", "Refused: bad signature". Start there when something a provider sent did not show up.
  3. Only when the user asks to connect a system: create_connection with kind stripe or dodo (mapped for you) or generic with a mapping. It returns the secret address once; give it to the user to paste into that system. From then on what arrives is recorded without anyone looking, and can start automations that send email.
  4. update_connection with enabled: false pauses a connection (its address answers 404); delete_connection removes it. The provider's signing secret and a replacement address are set by a person in the dashboard.
What one person did
{
  "name": "list_events",
  "arguments": {
    "contact": "ada@example.net"
  }
}

12. Check an email's content before it is sent

score_email reads a subject, the HTML and the plain text as they were written and returns a score from 0 to 100 with what to change, most points first. A plain email with no links and no images scores 100; a designed layout, links to another site than the sender's, link shorteners, images with few words, hidden text, capitals and very long HTML each take points off. Pass from so links can be compared with the sender's own domain. Nothing is stored or sent, and the footer and tracking SendHQ adds are not scored. The dashboard's email editor shows the same number for the same content. It looks at content only, so use it as a checklist: sender reputation, authentication and how recipients react decide more of where mail lands.

Score a draft
{
  "name": "score_email",
  "arguments": {
    "from": "hello@example.com",
    "subject": "Your cart is still here",
    "html": "<p>Pick up where you left off.</p><p><a href=\"https://bit.ly/3xyz\">Finish checkout</a></p>"
  }
}

结果、分页与错误

调用成功时,会将 API 的 JSON 对象同时作为 structuredContent 和 JSON 文本块返回。每个 list_* 工具都接受 limit(1–200,默认 50)和 offset,并附加一个 pagination 对象。只要 has_more 为 true,就继续使用 offset: pagination.next_offset 调用。

分页结果
{
  "data": [
    "…"
  ],
  "count": 50,
  "pagination": {
    "offset": 0,
    "limit": 50,
    "returned": 50,
    "total": 180,
    "has_more": true,
    "next_offset": 50
  }
}

调用失败时,会返回 isError: true 以及一个结构化错误。请按照 remedy 处理,不要盲目重试;只有当 retryable 为 true 时才重试。

结构化的工具错误
{
  "error": {
    "code": "subscription_required",
    "status": 402,
    "message": "Sending requires an active SendHQ subscription. Choose a plan to start sending.",
    "retryable": false,
    "explanation": "This workspace has no active paid subscription. SendHQ does not send any email, including to the account owner, until a plan is active.",
    "remedy": "Ask the account owner to choose a plan at https://sendhq.cc/pricing or in the dashboard (Profile & Billing). Do not retry until the subscription is active."
  }
}

可选的错误字段:request_id(联系支持时请提供)、retry_after_seconds、problems(invalid_arguments 对应的 schema 违规列表)以及 idempotent_replayed(参见“幂等”)。

幂等

send_email 和 send_batch 接受 idempotency_key(最多 200 个字符),并以 Idempotency-Key 请求头发送。请为每封逻辑邮件生成一个稳定的 key,例如 invoice-4812-receipt。

  • 重试时必须使用相同的 key,并且请求体完全相同。同一个 key 下出现任何变化(收件人、主题、正文、邮件头、模板数据,甚至参数值)都会返回 409 idempotency_conflict。
  • 相同的 key、相同的请求体,且原请求已完成:SendHQ 会返回已存储的结果,而不会再次发送。这就是在超时或 network_error 之后安全重试的方法。
  • 原请求仍在处理中时使用相同的 key:返回 409 idempotency_in_progress,稍等片刻后可重试。
  • 新的逻辑邮件需要新的 key。
  • 已存储的失败结果同样会被重放。如果第一次尝试失败,使用相同 key 重试会返回同样的失败,并带有 idempotent_replayed: true 和 retryable: false。请检查 list_emails(direction: out)确认没有邮件发出,修复问题根源,然后使用一个新的 key 发送。
  • 服务器从不自行重试 POST 请求。只有只读的 GET 调用会被自动重试(在网络错误、429 和 5xx 时最多尝试 3 次)。
  • 带有内联 attachments 的 send_email 不能使用 idempotency_key,因为它会执行多个请求。要实现可安全重试的附件发送,请按以下流程:create_draft → upload_attachment → 使用 draft_id 和 idempotency_key 调用 send_email。
可安全重试的发送(超时后原样重复)
{
  "name": "send_email",
  "arguments": {
    "from": "Acme <billing@example.com>",
    "to": [
      "owner@example.com"
    ],
    "subject": "Receipt #4812",
    "text": "Thanks for your payment.",
    "idempotency_key": "receipt-4812"
  }
}

速率限制与配额

SendHQ 没有为 API 公布固定的每秒请求数上限。智能体实际会遇到的是用量限制,以 429 返回:

  • 每月收件人投递数,按套餐计算。每个 To、Cc 和 Bcc 地址各计为一次投递。请对比 get_account → usage.recipientDeliveries 与 usage.emailQuotaMonth。
  • 每个具体 From 地址的每日收件人数,由该发件人的信誉状态决定(list_sender_reputation → dailyLimit,付费套餐默认为 2,000)。
  • Subscription: sending is refused with subscription_required until a paid plan is active. There is no free or trial allowance.
  • Workspace daily ladder on paid plans: 1,000 recipients on day one, then 2,000, 3,000, 5,000, 8,000, 12,000, 18,000, 25,000, 35,000, 45,000, and 50,000. A step is gained after a UTC day that used at least half the cap with healthy 7-day feedback. A high rate demotes once per incident, not every day the rate stays high. See get_account → sendingLimit. Over the cap: daily_limit_reached, not queued, retry after resets_at (midnight UTC), not on a short backoff.
  • Hourly pace: about one tenth of the day's cap each UTC hour (100 on day one). hourly_limit_reached waits until the next UTC hour.
  • New domains: a sending domain less than 30 days old may send at most 500 Gmail recipients a day (gmail_recipient_limit), on any ladder rung. gmail_rate_limited means Gmail returned 4.7.28; wait until resets_at and keep sending to other providers.
  • 附件:每封邮件最多 10 个文件、10 MB;付费套餐每月有 10 GB 按收件人加权计算的附件传输量。
  • 单次请求:To + Cc + Bcc 最多 100 个地址;send_batch 最多 100 封邮件。
  • 信誉熔断器:在滚动的 7 天窗口内,如果退信或投诉超过阈值,某个 From 地址会被限流或暂停(423 sender_paused)。比率回落后会自动恢复。

quota_exhausted 在周期重置或套餐变更之前不可重试。rate_limited 可在 retry_after_seconds 之后重试;对于发送操作,请使用相同的 idempotency_key 和完全相同的请求体重试。

错误目录

code 是稳定的;请根据它而不是 message 进行分支处理。

codeHTTP可重试?含义及处理方式
invalid_arguments—否参数未通过工具在本地的 JSON Schema 校验;没有任何请求到达 SendHQ。请修正 problems 中列出的字段。
auth_error401否API 密钥缺失、已被吊销或不正确。请为服务器进程设置 SENDHQ_API_KEY;密钥需由人在控制台中创建。
subscription_required402否No active subscription. Nothing is sent, including to the account owner. The owner chooses a plan. Do not retry until then.
payment_required402否该功能需要付费套餐(例如附件)。请不使用该功能发送,或升级套餐。
sender_domain_not_owned403否From 域名不在此工作区中。请使用 list_sending_identities 或 add_domain。
sender_domain_unverified403否From 域名尚未通过验证。请调用 get_domain,发布缺失的记录,然后调用 verify_domain。
domain_limit_reached403否已达到套餐的域名数量上限。请移除一个未使用的域名(需经批准)或升级套餐。
marketing_not_enabled403否此域名或套餐未启用营销类邮件。只有当邮件确实属于事务性邮件时,才可使用 transactional。
forbidden403否策略不允许执行该操作。请调整请求。
not_found404否该 ID 不在此工作区中。请列出该资源以找到正确的 ID;对于已归档的模板,请先恢复。
idempotency_conflict409否key 被复用于不同的请求体。请原样重新发送原始请求,或为新邮件使用新的 key。
idempotency_in_progress409是原请求仍在处理中。请等待,然后使用相同的 key 和请求体重试。
revision_conflict409否模板草稿在您读取之后已被修改。请调用 get_template,合并后重新保存。
complaint_suppression_locked409否收件人投诉过。永远不要再给对方发邮件。
inbound_not_ready409否入站收信尚未就绪。请调用 setup_inbound,发布 MX 记录,然后调用 verify_inbound。
conflict409否资源已存在或处于错误的状态。请先读取该资源再进行调整。
attachments_too_large413否超过 10 个文件或 10 MB。请移除或缩小附件。
recipient_suppressed422否某个收件人之前发生过硬退信或投诉。请将其移除;参见 list_blocked_recipients。
recipient_unsubscribed422否某个收件人已退订营销邮件。请将其永久移除。
validation_failed422否内容被拒绝,例如模板数据违反了变量约定。请修正输入。
sender_paused423否此 From 地址已被 7 天退信/投诉熔断器暂停。请停止发送、修正收件人列表,并等待自动恢复。
account_paused423否Workspace paused for a deliverability review. The body has the measured rate and the limit when the pause was for bounces or complaints. Do not send until it is restored.
quota_exhausted429否Monthly allowance, per-sender daily limit, or attachment transfer. Not the workspace daily ladder. Check get_account; wait for that limit to reset or upgrade.
daily_limit_reached429after resetWorkspace daily ladder. Not a short backoff. Wait until resets_at (midnight UTC). The message was not queued.
hourly_limit_reached429after resetHourly pace (about a tenth of the day's cap). Wait until the next UTC hour. Not a short backoff.
gmail_recipient_limit429after reset500 Gmail recipients a day for a sending domain under 30 days old, on any ladder rung. Wait until midnight UTC. Not queued.
gmail_rate_limited429after resetGmail returned 4.7.28 for this domain. Wait until resets_at. Other providers keep sending.
rate_limited429是Slow down; wait retry_after_seconds. This is not a daily, hourly, or Gmail cap.
server_error5xx是SendHQ 或服务商暂时故障。请退避后重试;发送操作使用相同的 key 和请求体。如果 idempotent_replayed 为 true,请在确认没有邮件发出后使用新的 key。
network_error—是请求或响应丢失。请重试;对于发送操作,使用相同的 idempotency_key 可确保重试安全。
invalid_request400否请求格式错误。请阅读 message 并加以修正。
tool_error—否MCP 服务器内部的本地故障(例如 file_path 无法读取)。请阅读 message。

工具参考

列出每个工具的安全类别、它调用的 REST 端点、参数、返回结构,以及一个 tools/call 参数对象示例。参数是精确的:服务器会拒绝任何未列出的参数。

Emails and threads: send_email, send_batch, list_emails, get_email, mark_email, delete_email, list_email_events, get_thread, email_delivery, thread_delivery
Labels and auto-filing rules: list_labels, get_label, create_label, update_label, delete_label, create_label_rule, delete_label_rule, label_email
Drafts, attachments, and sender identities: list_sending_identities, create_draft, list_drafts, get_draft, update_draft, delete_draft, upload_attachment, download_attachment, delete_attachment
Hosted templates: list_templates, create_template, get_template, update_template_draft, create_template_draft, render_template, send_template_test, publish_template, archive_template, restore_template
Domains and DNS: list_domains, get_domain, add_domain, verify_domain, delete_domain, get_dns_provider, get_domain_connect_link
Inbound email: setup_inbound, verify_inbound, list_inboxes, get_inbox, create_inbox, update_inbox, set_inbox_forwarding, delete_inbox
Deliverability, bounces, and suppressions: deliverability_stats, deliverability_account, deliverability_domains, deliverability_senders, score_email, list_sender_reputation, list_suppressions, remove_suppression, list_blocked_recipients
Campaigns: list_contacts, create_contact, upsert_contact, get_contact, update_contact, delete_contact, import_contacts, list_contact_imports, bulk_update_contacts, list_tags, list_contact_fields, set_contact_field, delete_contact_field, list_segments, get_segment, preview_segment, create_segment, update_segment, delete_segment, list_lists, create_list, get_list, update_list, delete_list, add_list_contacts, remove_list_contact, list_broadcasts, create_broadcast, get_broadcast, update_broadcast, delete_broadcast, send_broadcast, cancel_broadcast, list_broadcast_recipients, check_broadcast, send_broadcast_test, schedule_broadcast, unschedule_broadcast, duplicate_broadcast, send_broadcast_to_more, get_broadcast_report, get_newsletter_settings, update_newsletter_settings, get_campaign_overview, list_uploaded_images
Automations, events, and sending limits: track_event, list_automations, get_automation, create_automation, update_automation, delete_automation, set_automation_step, delete_automation_step, set_automation_step_variant, set_automation_status, send_automation_test_email, send_automation_test, enroll_contact, exit_contact, preview_automation, get_automations_overview, get_automation_report, list_automation_people, get_automation_person, get_sending_limits, update_sending_limits, list_automation_templates, get_automation_template, use_automation_template, list_events, list_event_names, list_connections, get_connection, create_connection, update_connection, delete_connection
Account, usage, analytics, and keys: get_account, get_account_diagnostics, get_analytics, list_api_keys, get_service_health

邮件与会话

发送真实邮件send_email
POST /emails

发送一封邮件

SENDS REAL EMAIL. Send one message from a verified domain: raw html/text, a published hosted template, a reply in an existing thread, or a message with attachments. Pass idempotency_key so a retry cannot send twice; a retry must reuse the same key AND an identical request, otherwise SendHQ returns 409. attachments is a convenience that creates a draft, uploads each file, and sends with that draft; it cannot be combined with idempotency_key or draft_id (use create_draft + upload_attachment + send_email with draft_id for retry-safe attachment sends). Unpaid workspaces (integration trial) can deliver only to the account email or a mailbox-simulator test address, and cannot send attachments.

至少提供以下之一:html、text、template。

参数类型必填说明
fromstring是发件人,例如 Acme <hello@example.com>。该域名必须已在此工作区中通过验证(参见 list_sending_identities)。(最多 998 个字符)
tostring[]是收件人。每一项是一个地址,可附带显示名称。to+cc+bcc 合计最多 100 个;每个目标地址消耗一个投递额度。(1–100 项)
ccstring[]否抄送收件人。(0–100 项)
bccstring[]否密送收件人。(0–100 项)
subjectstring否主题行。发送模板时请省略。(最多 998 个字符)
textstring否纯文本正文。请提供 text、html 或 template 之一。
htmlstring否HTML 正文。SendHQ 会对其进行清理,并在省略 text 时自动生成纯文本。
reply_tostring否Reply-To 地址。
headersobject否额外的安全自定义邮件头(值为字符串),例如 {"X-Entity-Ref-ID": "123"}。From/To/Message-ID 等路由类邮件头由 SendHQ 控制。
message_classstring否transactional(默认)或 marketing。营销邮件需要启用了营销功能的套餐或域名,并会添加退订处理。(取值为 transactional、marketing 之一)
reply_to_email_idstring否在现有会话中回复:被回复邮件的 em_… ID。SendHQ 会设置 In-Reply-To/References 和会话。
thread_idstring否将邮件归入的显式会话 ID。
draft_idstring否随此邮件发送某个已存储草稿(dr_…)的附件。发送成功后该草稿会被删除。
templateobject否发送已发布的托管模板,而不是原始 html/text。要求恰好一个 to 收件人,且不能有 cc/bcc;主题由模板提供。至少提供以下之一:id、key。
template.idstring否模板 ID(tmpl_…)。请提供 id 或 key。
template.keystring否模板 key,例如 account-welcome。请提供 id 或 key。
template.version_idstring否可选的已发布版本 ID(tmplv_…)。默认为当前已发布的版本。
template.dataobject否模板类型化变量的取值。
labelsstring[]否用于归档此邮件的标签名称或 lbl_… ID。不存在的名称会被自动创建。会话中的回复会继承这些标签,而分类标签(skip_inbox)会让这些回复不进入收件箱。最多 10 个。(0–10 项)
idempotency_keystring否Idempotency-Key 请求头(最多 200 个字符)。仅在重试这一完全相同的请求时复用。(最多 200 个字符)
attachmentsobject[]否要附加的文件(最多 10 个文件,总计 10 MB)。每个文件需要提供 content_base64(外加 filename)或本地 file_path。(0–10 项)至少提供以下之一:content_base64、file_path。
attachments[].filenamestring否向收件人显示的文件名。使用 content_base64 时必填;默认为 file_path 的基本名称。(最多 255 个字符)
attachments[].content_typestring否MIME 类型,例如 application/pdf。默认为 application/octet-stream。
attachments[].content_base64string否标准 base64 编码的文件内容。
attachments[].file_pathstring否MCP 服务器进程可读取的本地文件的绝对路径。
返回{id: em_…, providerMessageId, threadId, templateId, templateVersionId, isTest}。已受理不等于已送达:请随后调用 list_email_events 跟进。
tools/call 参数示例
{
  "name": "send_email",
  "arguments": {
    "from": "Acme <hello@example.com>",
    "to": [
      "owner@example.com"
    ],
    "subject": "Your export is ready",
    "text": "Download it from your dashboard.",
    "idempotency_key": "export-ready-42"
  }
}
发送真实邮件send_batch
POST /emails/batch

批量发送个性化邮件

SENDS REAL EMAIL(发送真实邮件)。在一个请求中发送 1–100 封相互独立的邮件(按收件人个性化模板时请使用此工具)。每一项的结构与 send_email 相同(不含 attachments/idempotency_key)。各项分别成功或失败:HTTP 207 表示部分成功;请检查每一项的 data[i].ok 和 data[i].error。一个 idempotency_key 覆盖整个批量请求体。

参数类型必填说明
emailsobject[]是要发送的邮件。(1–100 项)至少提供以下之一:html、text、template。
idempotency_keystring否整个批量请求的 Idempotency-Key(最多 200 个字符)。(最多 200 个字符)
返回{data: [{index, ok, id?, error?: {message, status}}], count, successful, failed}。
tools/call 参数示例
{
  "name": "send_batch",
  "arguments": {
    "emails": [
      {
        "from": "Acme <hello@example.com>",
        "to": [
          "owner@example.com"
        ],
        "template": {
          "key": "account-welcome",
          "data": {
            "first_name": "Asha"
          }
        }
      }
    ],
    "idempotency_key": "welcome-batch-2026-09-26"
  }
}
只读list_emails
GET /emails

列出和搜索邮件

按从新到旧的顺序列出已发送(direction: out)和已收到(direction: in)的邮件,支持筛选。收到的邮件会被分类:使用 direction: in、archived: false、category: primary 读取人类用户的收件箱;使用 important: true 进行分诊;垃圾邮件默认隐藏,除非指定 category: spam 或 include_spam: true。结果分页:包含 pagination {offset, limit, returned, total?, has_more, next_offset}。

参数类型必填说明
directionstring否in 表示收到的邮件,out 表示发出的邮件。(取值为 in、out 之一)
statusstring否状态筛选,例如 queued、sent、delivered、bounced、complained、failed。
domainstring否只返回该域名的邮件,或逗号分隔的域名列表(匹配其中任意一个)。
inbox_idstring否只返回该收件箱(inb_…)收到的邮件。
labelstring否只返回带有该标签的邮件:标签 ID lbl_… 或准确的名称,也可以是逗号分隔的列表(匹配其中任意一个)。使用 list_labels 查看文件夹。
archivedboolean否false = 收件箱视图(未归档的收到邮件),true = 仅已归档邮件。省略则返回所有邮件。
categorystring否primary(真人来信)、updates(新闻通讯、群发、自动邮件)或 spam;也可以是逗号分隔的列表。除非明确请求,否则垃圾邮件会被隐藏。
importantboolean否true = 只返回被标记为重要的邮件(对您发起的会话的回复,以及被标记为重要的发件人的邮件)。
include_spamboolean否在结果中包含垃圾邮件(用于跨所有文件夹搜索)。
fromstring否发件人地址包含此值。
tostring否收件人地址包含此值。
unreadboolean否true = 仅未读,false = 仅已读。
afterstring否ISO-8601 时间戳;只返回在此之后创建的邮件。(date-time)
beforestring否ISO-8601 时间戳;只返回在此之前创建的邮件。(date-time)
querystring否对主题、正文、发件人/收件人地址和附件文件名进行全文搜索。(最多 200 个字符)
limitinteger否每页条数。默认为 50。(默认 50;1–200)
offsetinteger否要跳过的记录数。请使用上一页返回的 pagination.next_offset。(默认 0;0–…)
返回{data: [邮件摘要], count, pagination}。
注解readOnlyHint idempotentHint
tools/call 参数示例
{
  "name": "list_emails",
  "arguments": {
    "direction": "in",
    "unread": true,
    "limit": 25
  }
}
只读get_email
GET /emails/:email_id

获取一封邮件

获取一封邮件,包括邮件头、html/text 正文、状态、会话元数据和附件元数据(附件内容请用 download_attachment 下载)。

参数类型必填说明
email_idstring是邮件 ID(以 em_ 开头),由列表或创建类工具返回。(最多 128 个字符)
返回邮件对象:{id, direction, status, from, to, cc, bcc, subject, html, text, threadId, messageId, providerMessageId, readAt, createdAt, attachments: [{id, filename, contentType, sizeBytes, available}]}。
注解readOnlyHint idempotentHint
tools/call 参数示例
{
  "name": "get_email",
  "arguments": {
    "email_id": "em_123"
  }
}
改变状态mark_email
PATCH /emails/:email_id

标记为已读、已归档、垃圾邮件或重要

更新一封邮件:read、archived、category(primary、updates、spam;仅限收到的邮件)和 important。举报垃圾邮件或标记为重要会让 SendHQ 记住该发件人,用于今后的邮件;传入 learn: false 则只更改这一封邮件。至少传入一个字段。

参数类型必填说明
email_idstring是邮件 ID(以 em_ 开头),由列表或创建类工具返回。(最多 128 个字符)
readboolean否true = 已读,false = 未读。
archivedboolean否true = 归档(跳过收件箱),false = 移回收件箱。
categorystring否将收到的邮件移至 primary、updates 或 spam。(取值为 primary、updates、spam 之一)
importantboolean否将邮件标记为重要或取消重要标记。
learnboolean否false = 不为该发件人记住此判定(默认为 true)。
返回更新后的邮件对象。
注解idempotentHint
tools/call 参数示例
{
  "name": "mark_email",
  "arguments": {
    "email_id": "em_123",
    "read": true
  }
}
破坏性操作delete_email
DELETE /emails/:email_id

删除一封邮件

DESTRUCTIVE(破坏性操作):从 SendHQ 中永久删除一封已保留的邮件及其存储的附件。它不会撤回已经投递的邮件。

参数类型必填说明
email_idstring是邮件 ID(以 em_ 开头),由列表或创建类工具返回。(最多 128 个字符)
返回{ok: true}。
注解destructiveHint idempotentHint
tools/call 参数示例
{
  "name": "delete_email",
  "arguments": {
    "email_id": "em_123"
  }
}
只读list_email_events
GET /emails/:email_id/events

列出某封邮件的投递事件

一封已发送邮件的服务商事件:delivery、bounce、complaint、reject、open、click。这是判断邮件是否已送达或失败原因的证据。结果分页:包含 pagination {offset, limit, returned, total?, has_more, next_offset}。

参数类型必填说明
email_idstring是邮件 ID(以 em_ 开头),由列表或创建类工具返回。(最多 128 个字符)
limitinteger否每页条数。默认为 50。(默认 50;1–200)
offsetinteger否要跳过的记录数。请使用上一页返回的 pagination.next_offset。(默认 0;0–…)
返回{data: [{event_type, recipient, reason, created_at, …}], count, pagination}。
注解readOnlyHint idempotentHint
tools/call 参数示例
{
  "name": "list_email_events",
  "arguments": {
    "email_id": "em_123"
  }
}
只读get_thread
GET /threads/:thread_id

获取一个会话

按时间顺序获取会话中的每一封邮件(包括发出和收到的),每封邮件都附带附件元数据。

参数类型必填说明
thread_idstring是会话 ID(通常是第一封邮件的 em_… ID;参见任意邮件上的 threadId)。(最多 128 个字符)
返回{id, subject, data: [邮件]}。
注解readOnlyHint idempotentHint
tools/call 参数示例
{
  "name": "get_thread",
  "arguments": {
    "thread_id": "em_123"
  }
}
Read-onlyemail_delivery
GET /emails/:email_id/delivery

Get an email delivery timeline

Queued, sent, delivered, delayed, bounced, complained, and failed events for one email, with bounce type and the SMTP diagnostic. Reasons are plain text.

参数类型必填说明
email_idstring是
limitinteger否
offsetinteger否
Returns{emailId, status, timeline, count, limit, offset}.
注解readOnlyHint idempotentHint
tools/call 参数示例
{
  "name": "email_delivery",
  "arguments": {
    "email_id": "em_123"
  }
}
Read-onlythread_delivery
GET /threads/:thread_id/delivery

Get a thread delivery summary

Counts of delivered, bounced, complained, and failed outbound messages in one conversation, plus each message's failure reason.

参数类型必填说明
thread_idstring是
Returns{threadId, delivered, bounced, complained, failed, messages}.
注解readOnlyHint idempotentHint
tools/call 参数示例
{
  "name": "thread_delivery",
  "arguments": {
    "thread_id": "thr_123"
  }
}

标签与自动归档规则

只读list_labels
GET /labels

列出标签

列出工作区的标签(文件夹),包括总数、未读数及其自动归档规则。结果分页:包含 pagination {offset, limit, returned, total?, has_more, next_offset}。

参数类型必填说明
limitinteger否每页条数。默认为 50。(默认 50;1–200)
offsetinteger否要跳过的记录数。请使用上一页返回的 pagination.next_offset。(默认 0;0–…)
返回{data: [{id, name, color, totalCount, unreadCount, rules: [...]}], count, pagination}。
注解readOnlyHint idempotentHint
tools/call 参数示例
{
  "name": "list_labels",
  "arguments": {}
}
只读get_label
GET /labels/:label_id

获取一个标签

获取一个标签及其计数和自动归档规则。

参数类型必填说明
label_idstring是标签 ID(以 lbl_ 开头)或准确的标签名称。(最多 128 个字符)
返回标签对象。
注解readOnlyHint idempotentHint
tools/call 参数示例
{
  "name": "get_label",
  "arguments": {
    "label_id": "Billing"
  }
}
改变状态create_label
POST /labels

创建标签

创建一个文件夹式的标签。设置 skip_inbox: true 可将其变为由智能体拥有的分类:使用 labels: [name] 发送后,回复会被归入该标签,而不会进入收件箱。可选的自动归档规则会归档新发出/收到的邮件(规则上的每个条件都必须匹配)。设置 apply_to_existing 还会归档已保留的邮件。

参数类型必填说明
namestring是标签名称,例如 Billing 或 Clients/Acme。在工作区内唯一(不区分大小写)。(最多 64 个字符)
colorstring否十六进制颜色,例如 #1a73e8。可选。
skip_inboxboolean否分类模式:收到的邮件如果获得该标签(通过规则、作为带此标签发出的会话的回复,或手动添加),都会被归档,因此只会出现在该标签中,而不会出现在收件箱里。
rulesobject[]否可选的自动归档规则(最多 20 条)。每条规则至少需要 inbox_id、from、to、subject 之一。(0–20 项)
rules[].directionstring否只匹配 in(收到)或 out(发出)的邮件。省略则两者都匹配。(取值为 in、out 之一)
rules[].inbox_idstring否只匹配该收件箱(inb_…)收到的邮件。可将每个收件地址归入各自的文件夹。
rules[].fromstring否发件人包含此文本(不区分大小写),例如 @stripe.com。(最多 200 个字符)
rules[].tostring否To/Cc 包含此文本(不区分大小写)。(最多 200 个字符)
rules[].subjectstring否主题包含此文本(不区分大小写)。(最多 200 个字符)
rules[].skip_inboxboolean否将匹配的收到邮件归档,使其只出现在标签文件夹中,而不出现在收件箱里。
apply_to_existingboolean否同时归档符合规则的已保留邮件。
返回创建好的标签及其规则。
tools/call 参数示例
{
  "name": "create_label",
  "arguments": {
    "name": "Agent/Orders",
    "skip_inbox": true,
    "rules": [
      {
        "from": "@stripe.com"
      }
    ]
  }
}
改变状态update_label
PATCH /labels/:label_id

重命名标签、更改颜色或设为分类

重命名标签、更改其颜色,或切换分类模式(skip_inbox)。开启分类模式时,会将标签中已有的收到邮件归档。

参数类型必填说明
label_idstring是标签 ID(以 lbl_ 开头)或准确的标签名称。(最多 128 个字符)
namestring否新名称。(最多 64 个字符)
colorstring否新的十六进制颜色。
skip_inboxboolean否分类模式:收到的邮件如果获得该标签(通过规则、作为带此标签发出的会话的回复,或手动添加),都会被归档,因此只会出现在该标签中,而不会出现在收件箱里。
返回更新后的标签。
注解idempotentHint
tools/call 参数示例
{
  "name": "update_label",
  "arguments": {
    "label_id": "lbl_123",
    "name": "Finance/Billing"
  }
}
破坏性操作delete_label
DELETE /labels/:label_id

删除标签

DESTRUCTIVE(破坏性操作):删除一个标签及其规则。邮件本身会保留,只是不再带有该标签。

参数类型必填说明
label_idstring是标签 ID(以 lbl_ 开头)或准确的标签名称。(最多 128 个字符)
返回{ok: true}。
注解destructiveHint idempotentHint
tools/call 参数示例
{
  "name": "delete_label",
  "arguments": {
    "label_id": "lbl_123"
  }
}
改变状态create_label_rule
POST /labels/:label_id/rules

添加自动归档规则

为标签添加一条规则,使匹配的新邮件被自动归档。您设置的每个条件都必须匹配。使用 inbox_id 可为某个收件地址分配独立的文件夹;添加 skip_inbox 可使其不进入收件箱。

参数类型必填说明
label_idstring是标签 ID(以 lbl_ 开头)或准确的标签名称。(最多 128 个字符)
directionstring否只匹配 in(收到)或 out(发出)的邮件。省略则两者都匹配。(取值为 in、out 之一)
inbox_idstring否只匹配该收件箱(inb_…)收到的邮件。可将每个收件地址归入各自的文件夹。
fromstring否发件人包含此文本(不区分大小写),例如 @stripe.com。(最多 200 个字符)
tostring否To/Cc 包含此文本(不区分大小写)。(最多 200 个字符)
subjectstring否主题包含此文本(不区分大小写)。(最多 200 个字符)
skip_inboxboolean否将匹配的收到邮件归档,使其只出现在标签文件夹中,而不出现在收件箱里。
apply_to_existingboolean否同时归档符合条件的已保留邮件。
返回{id: lrule_…, labelId, direction, inboxId, from, to, subject, skipInbox}。
tools/call 参数示例
{
  "name": "create_label_rule",
  "arguments": {
    "label_id": "Billing",
    "inbox_id": "inb_123",
    "skip_inbox": true
  }
}
破坏性操作delete_label_rule
DELETE /labels/:label_id/rules/:rule_id

删除自动归档规则

DESTRUCTIVE(破坏性操作):移除一条自动归档规则。已归档的邮件会保留其标签。

参数类型必填说明
label_idstring是标签 ID(以 lbl_ 开头)或准确的标签名称。(最多 128 个字符)
rule_idstring是规则 ID(以 lrule_ 开头),可从 get_label 获取。(最多 128 个字符)
返回{ok: true}。
注解destructiveHint idempotentHint
tools/call 参数示例
{
  "name": "delete_label_rule",
  "arguments": {
    "label_id": "lbl_123",
    "rule_id": "lrule_123"
  }
}
改变状态label_email
POST /emails/:email_id/labels

为邮件添加或移除标签

在文件夹之间移动邮件:按名称或 lbl_… ID 添加和/或移除标签。add 中不存在的名称会被自动创建,除非 create 为 false。

参数类型必填说明
email_idstring是邮件 ID(以 em_ 开头),由列表或创建类工具返回。(最多 128 个字符)
addstring[]否要添加的标签。(0–10 项)
removestring[]否要移除的标签。(0–10 项)
createboolean否自动创建 add 中不存在的标签(默认为 true)。
返回带有 labels 的更新后邮件。
注解idempotentHint
tools/call 参数示例
{
  "name": "label_email",
  "arguments": {
    "email_id": "em_123",
    "add": [
      "Billing"
    ],
    "remove": [
      "Support"
    ]
  }
}

草稿、附件与发信身份

只读list_sending_identities
GET /sending-identities

列出已验证的发信身份

此工作区当前可用于发信的地址和域名(已验证域名、其默认 From 地址,以及处于启用状态的收件箱地址)。请在调用 send_email 之前调用它,以选择有效的 from。

无参数。

返回{domains: [已验证的域名], addresses: [发件地址], localParts: [...]}。
注解readOnlyHint idempotentHint
tools/call 参数示例
{
  "name": "list_sending_identities",
  "arguments": {}
}
改变状态create_draft
POST /drafts

创建草稿

创建一份撰写草稿。草稿用于存放附件:先创建草稿,再调用 upload_attachment,然后使用 draft_id 调用 send_email。此操作不会发送任何内容。

参数类型必填说明
fromstring否位于已验证域名上的发件地址(起草期间可以为空)。
tostring[]否收件人。(0–100 项)
ccstring[]否抄送收件人。(0–100 项)
bccstring[]否密送收件人。(0–100 项)
subjectstring否主题行。(最多 998 个字符)
htmlstring否HTML 正文。
textstring否纯文本正文。
reply_to_email_idstring否此草稿所回复的邮件 ID。
thread_idstring否此草稿所属的会话 ID。
返回草稿对象 {id: dr_…, from, to, cc, bcc, subject, html, text, attachments: []}。
tools/call 参数示例
{
  "name": "create_draft",
  "arguments": {
    "from": "hello@example.com",
    "to": [
      "owner@example.com"
    ],
    "subject": "Invoice"
  }
}
只读list_drafts
GET /drafts

列出草稿

列出撰写草稿,按最近更新时间排序。结果分页:包含 pagination {offset, limit, returned, total?, has_more, next_offset}。

参数类型必填说明
limitinteger否每页条数。默认为 50。(默认 50;1–200)
offsetinteger否要跳过的记录数。请使用上一页返回的 pagination.next_offset。(默认 0;0–…)
返回{data: [草稿], count, pagination}。
注解readOnlyHint idempotentHint
tools/call 参数示例
{
  "name": "list_drafts",
  "arguments": {}
}
只读get_draft
GET /drafts/:draft_id

获取一份草稿

获取一份草稿及其附件元数据。

参数类型必填说明
draft_idstring是草稿 ID(以 dr_ 开头),由列表或创建类工具返回。(最多 128 个字符)
返回带有 attachments 的草稿对象。
注解readOnlyHint idempotentHint
tools/call 参数示例
{
  "name": "get_draft",
  "arguments": {
    "draft_id": "dr_123"
  }
}
改变状态update_draft
PUT /drafts/:draft_id

替换草稿内容

替换草稿的内容和收件人。这是完全替换:省略的字段会被清空,因此请先调用 get_draft 读取,并发送您想保留的每一个字段。附件不受影响。

参数类型必填说明
draft_idstring是草稿 ID(以 dr_ 开头),由列表或创建类工具返回。(最多 128 个字符)
fromstring否位于已验证域名上的发件地址(起草期间可以为空)。
tostring[]否收件人。(0–100 项)
ccstring[]否抄送收件人。(0–100 项)
bccstring[]否密送收件人。(0–100 项)
subjectstring否主题行。(最多 998 个字符)
htmlstring否HTML 正文。
textstring否纯文本正文。
reply_to_email_idstring否此草稿所回复的邮件 ID。
thread_idstring否此草稿所属的会话 ID。
返回更新后的草稿对象。
注解idempotentHint
tools/call 参数示例
{
  "name": "update_draft",
  "arguments": {
    "draft_id": "dr_123",
    "from": "hello@example.com",
    "to": [
      "owner@example.com"
    ],
    "subject": "Invoice (updated)",
    "text": "Attached."
  }
}
破坏性操作delete_draft
DELETE /drafts/:draft_id

丢弃草稿

DESTRUCTIVE(破坏性操作):丢弃一份草稿,并永久删除其存储的附件。

参数类型必填说明
draft_idstring是草稿 ID(以 dr_ 开头),由列表或创建类工具返回。(最多 128 个字符)
返回{ok: true}。
注解destructiveHint idempotentHint
tools/call 参数示例
{
  "name": "delete_draft",
  "arguments": {
    "draft_id": "dr_123"
  }
}
改变状态upload_attachment
POST /drafts/:draft_id/attachments

向草稿上传附件

向草稿上传一个文件(每封邮件最多 10 个文件,总计 10 MB)。请提供 content_base64 或本地 file_path。发送带附件的邮件时需要付费套餐。

至少提供以下之一:content_base64、file_path。

参数类型必填说明
draft_idstring是草稿 ID(以 dr_ 开头),由列表或创建类工具返回。(最多 128 个字符)
filenamestring否向收件人显示的文件名。默认为 file_path 的基本名称。(最多 255 个字符)
content_typestring否MIME 类型,例如 application/pdf。默认为 application/octet-stream。
content_base64string否标准 base64 编码的文件内容。
file_pathstring否MCP 服务器进程可读取的本地文件的绝对路径。
返回{id: att_…, filename, contentType, sizeBytes, available}。
tools/call 参数示例
{
  "name": "upload_attachment",
  "arguments": {
    "draft_id": "dr_123",
    "filename": "invoice.pdf",
    "content_type": "application/pdf",
    "file_path": "/tmp/invoice.pdf"
  }
}
只读download_attachment
GET /attachments/:attachment_id

下载附件

下载一个私有附件(已发送、已收到或草稿中的)。返回 base64 内容;如果设置了 save_to_path,则写入文件(除非 overwrite 为 true,否则拒绝覆盖)。

参数类型必填说明
attachment_idstring是附件 ID(以 att_ 开头),由列表或创建类工具返回。(最多 128 个字符)
save_to_pathstring否可选的本地绝对路径,用于写入文件,而不是返回 base64。
overwriteboolean否允许替换 save_to_path 处已存在的文件。默认为 false。
返回{attachment_id, filename, content_type, size_bytes, content_base64} 或 {attachment_id, filename, content_type, size_bytes, saved_to}。
注解readOnlyHint idempotentHint
tools/call 参数示例
{
  "name": "download_attachment",
  "arguments": {
    "attachment_id": "att_123",
    "save_to_path": "/tmp/invoice.pdf"
  }
}
破坏性操作delete_attachment
DELETE /attachments/:attachment_id

删除附件

DESTRUCTIVE(破坏性操作):永久删除一个已存储的附件(例如在发送前从草稿中移除某个文件)。

参数类型必填说明
attachment_idstring是附件 ID(以 att_ 开头),由列表或创建类工具返回。(最多 128 个字符)
返回{ok: true}。
注解destructiveHint idempotentHint
tools/call 参数示例
{
  "name": "delete_attachment",
  "arguments": {
    "attachment_id": "att_123"
  }
}

托管模板

只读list_templates
GET /templates

列出托管模板

列出托管邮件模板及其发布状态和使用情况。结果分页:包含 pagination {offset, limit, returned, total?, has_more, next_offset}。

参数类型必填说明
lifecyclestring否active(默认)、archived 或 all。(取值为 active、archived、all 之一)
querystring否按名称或 key 搜索。(最多 120 个字符)
limitinteger否每页条数。默认为 50。(默认 50;1–200)
offsetinteger否要跳过的记录数。请使用上一页返回的 pagination.next_offset。(默认 0;0–…)
返回{data: [模板], count, pagination}。
注解readOnlyHint idempotentHint
tools/call 参数示例
{
  "name": "list_templates",
  "arguments": {
    "lifecycle": "active"
  }
}
改变状态create_template
POST /templates

创建托管模板

创建一个带可编辑草稿的模板,可选择基于某个起始模板(welcome、reset、receipt 或 blank)。按 key 发送之前需要先发布。

参数类型必填说明
namestring是便于人阅读的名称。(最多 120 个字符)
keystring否稳定的发送 key:由小写字母、数字和连字符组成,以字母开头(2–64 个字符)。省略时根据名称生成。
starterstring否起始内容。(取值为 blank、welcome、reset、receipt 之一)
返回{template, draft, activeVersion, versions, usage}。
tools/call 参数示例
{
  "name": "create_template",
  "arguments": {
    "name": "Account welcome",
    "key": "account-welcome",
    "starter": "welcome"
  }
}
只读get_template
GET /templates/:template_id

获取模板

获取模板的当前草稿(含 revision)、当前生效的已发布版本、版本历史和使用情况。接受 ID 或 key。

参数类型必填说明
template_idstring是模板 ID(tmpl_…)或 key。(最多 128 个字符)
返回{template, draft: {id, revision, subjectTemplate, htmlTemplate, textTemplate, variables, sampleData, …} | null, activeVersion, versions, usage}。
注解readOnlyHint idempotentHint
tools/call 参数示例
{
  "name": "get_template",
  "arguments": {
    "template_id": "account-welcome"
  }
}
改变状态update_template_draft
PUT /templates/:template_id/draft

保存模板草稿

使用乐观并发保存模板的可编辑草稿:传入从 get_template 获取的当前 revision(409 表示其他人先保存了;请重新读取后重试)。这是对草稿内容的完全替换:省略的字段会被清空,因此请发送您想保留的每一个字段。请使用 {{variable}} 占位符。

参数类型必填说明
template_idstring是模板 ID 或 key。(最多 128 个字符)
revisioninteger是从 get_template 获取的当前草稿修订号。(1–…)
namestring否模板名称。(最多 120 个字符)
subject_templatestring否带占位符的主题。(最多 998 个字符)
preheader_templatestring否预览文本。(最多 240 个字符)
html_templatestring否带占位符的 HTML 正文。
text_templatestring否带占位符的纯文本正文。
fromstring否使用此模板发送时的默认发件人。
reply_tostring否默认的 Reply-To。
variablesobject[]否类型化的变量约定。每一项为:{key(小写字母/下划线), label, type: text|number|url|boolean, required(默认为 true), fallback, description}。
variables[].keystring是
variables[].labelstring否
variables[].typestring否(取值为 text、number、url、boolean 之一)
variables[].requiredboolean否
variables[].fallbackany否
variables[].descriptionstring否
sample_dataobject否用于预览和测试的示例值。
返回{template, draft: {revision: next}, validation: {valid, findings}}。
tools/call 参数示例
{
  "name": "update_template_draft",
  "arguments": {
    "template_id": "account-welcome",
    "revision": 3,
    "name": "Account welcome",
    "subject_template": "Welcome, {{first_name}}",
    "text_template": "Hi {{first_name}}",
    "variables": [
      {
        "key": "first_name",
        "type": "text",
        "required": true
      }
    ],
    "sample_data": {
      "first_name": "Asha"
    }
  }
}
改变状态create_template_draft
POST /templates/:template_id/draft

基于已发布版本新建草稿

从当前已发布的版本复制出一份新的可编辑草稿(如果草稿已存在或尚未发布任何版本,则返回 409)。

参数类型必填说明
template_idstring是模板 ID 或 key。(最多 128 个字符)
返回{draft}。
tools/call 参数示例
{
  "name": "create_template_draft",
  "arguments": {
    "template_id": "account-welcome"
  }
}
只读render_template
POST /templates/:template_id/render

渲染模板预览

使用给定数据,为草稿、已发布版本或指定版本渲染与服务端完全一致的输出(subject、html、text)。不会发送。当数据违反变量约定时,返回 422 并附带 findings。

参数类型必填说明
template_idstring是模板 ID 或 key。(最多 128 个字符)
version_idstring否可选的版本 ID;默认使用草稿,其次是已发布版本。
dataobject否变量值;默认使用该版本的示例数据。
返回{subject, html, text, preheader, versionId, versionNumber, isDraft, findings}。
注解readOnlyHint idempotentHint
tools/call 参数示例
{
  "name": "render_template",
  "arguments": {
    "template_id": "account-welcome",
    "data": {
      "first_name": "Asha"
    }
  }
}
发送真实邮件send_template_test
POST /templates/:template_id/test

发送模板测试邮件

SENDS REAL EMAIL. Send a [Test]-prefixed snapshot of the draft (or a given version) to the given recipients. Counts against usage; trial workspaces can only send to the account email or a mailbox-simulator test address.

参数类型必填说明
template_idstring是模板 ID 或 key。(最多 128 个字符)
tostring[]是测试收件人。(1–100 项)
fromstring否位于已验证域名上的发件人;默认为模板的 From。
version_idstring否可选的版本 ID。
dataobject否变量值;默认使用示例数据。
返回{id: em_…, providerMessageId, threadId, isTest: true}。
tools/call 参数示例
{
  "name": "send_template_test",
  "arguments": {
    "template_id": "account-welcome",
    "to": [
      "owner@example.com"
    ]
  }
}
改变状态publish_template
POST /templates/:template_id/publish

发布模板版本

将当前草稿发布为不可变的版本,供带 template.key 的 send_email 使用。如果存在校验错误,会以 422 失败并返回检查结果;如果会破坏已在生产环境中使用的模板的现行变量约定,则返回 409。

参数类型必填说明
template_idstring是模板 ID 或 key。(最多 128 个字符)
返回{template, published}。
tools/call 参数示例
{
  "name": "publish_template",
  "arguments": {
    "template_id": "account-welcome"
  }
}
改变状态archive_template
POST /templates/:template_id/archive

归档模板

停止使用此模板的新发送(历史记录会保留;可通过 restore_template 恢复)。任何使用此 key 发送的集成都会开始以 404 失败。

参数类型必填说明
template_idstring是模板 ID 或 key。(最多 128 个字符)
返回{template}。
注解idempotentHint
tools/call 参数示例
{
  "name": "archive_template",
  "arguments": {
    "template_id": "account-welcome"
  }
}
改变状态restore_template
POST /templates/:template_id/restore

恢复已归档的模板

让已归档的模板重新变为启用状态。

参数类型必填说明
template_idstring是模板 ID 或 key。(最多 128 个字符)
返回{template}。
注解idempotentHint
tools/call 参数示例
{
  "name": "restore_template",
  "arguments": {
    "template_id": "account-welcome"
  }
}

域名与 DNS

只读list_domains
GET /domains

列出域名

列出发信域名,包括汇总的 setup_status(verified | checking | pending)、每条记录的 DNS 状态以及入站状态。可能较慢:未验证的域名会被实时重新检查。结果分页:包含 pagination {offset, limit, returned, total?, has_more, next_offset}。

参数类型必填说明
limitinteger否每页条数。默认为 50。(默认 50;1–200)
offsetinteger否要跳过的记录数。请使用上一页返回的 pagination.next_offset。(默认 0;0–…)
返回{data: [带记录的域名], count, pagination}。
注解readOnlyHint idempotentHint
tools/call 参数示例
{
  "name": "list_domains",
  "arguments": {}
}
只读get_domain
GET /domains/:domain_id

获取域名配置详情

获取一个域名,包括需要发布的准确 DNS 记录(type、name、value)、从两个公共解析器获得的每条记录的实时状态、附带修复方法的 dns_issues,以及入站状态。

参数类型必填说明
domain_idstring是域名 ID(以 dom_ 开头),由列表或创建类工具返回。(最多 128 个字符)
返回{id, name, status, setup_status, dns_propagating, records: [{type, name, value, verified, dns_state}], dns_issues: [{code, message, …}], inbound_domain, inbound_status}。
注解readOnlyHint idempotentHint
tools/call 参数示例
{
  "name": "get_domain",
  "arguments": {
    "domain_id": "dom_123"
  }
}
改变状态add_domain
POST /domains

添加发信域名

Register a domain you control for sending. Returns the DNS records (Easy DKIM CNAMEs) the owner must publish. Does not change DNS itself. Counts against the plan's domain limit.

参数类型必填说明
namestring是裸域名,例如 example.com 或 mail.example.com。(最多 253 个字符)
default_fromstring否此域名上可选的默认发件地址。
返回{id: dom_…, name, status: pending, records: [...], ses: {configured}}。
tools/call 参数示例
{
  "name": "add_domain",
  "arguments": {
    "name": "example.com"
  }
}
改变状态verify_domain
POST /domains/:domain_id/verify

验证域名

Run a live DNS and DKIM verification check now. Safe to repeat; poll every 30–60 s after DNS changes (propagation can take minutes to hours). Sending is allowed once status is verified.

参数类型必填说明
domain_idstring是域名 ID(以 dom_ 开头),由列表或创建类工具返回。(最多 128 个字符)
返回{domain, checks: {ses, dkim, dkim_status}, status: verified|pending}。
注解idempotentHint
tools/call 参数示例
{
  "name": "verify_domain",
  "arguments": {
    "domain_id": "dom_123"
  }
}
破坏性操作delete_domain
DELETE /domains/:domain_id

删除域名

DESTRUCTIVE(破坏性操作):从工作区中移除该域名,包括其入站收信路由。此后从该域名发信会立即失败。它不会删除您 DNS 服务商处的 DNS 记录。

参数类型必填说明
domain_idstring是域名 ID(以 dom_ 开头),由列表或创建类工具返回。(最多 128 个字符)
返回{ok: true}。
注解destructiveHint idempotentHint
tools/call 参数示例
{
  "name": "delete_domain",
  "arguments": {
    "domain_id": "dom_123"
  }
}
只读get_dns_provider
GET /dns/provider

检测 DNS 服务商和记录主机名

检测该域名的权威 DNS 服务商,并返回在该服务商处每条记录应输入的相对主机名、推荐的 DMARC 记录、入站 MX 指引,以及是否支持一键配置(Domain Connect)。

参数类型必填说明
domain_idstring是域名 ID(以 dom_ 开头),由列表或创建类工具返回。(最多 128 个字符)
返回{detectionStatus, detected, zone, nameservers, recordHosts: {recordId: host}, inbound, recommendations, authentication, providers: {domainConnect: {available, providerName}}}。
注解readOnlyHint idempotentHint
tools/call 参数示例
{
  "name": "get_dns_provider",
  "arguments": {
    "domain_id": "dom_123"
  }
}

入站邮件

改变状态setup_inbound
POST /domains/:domain_id/inbound/setup

为域名启用入站收信

Provision inbound receiving for a verified domain. Uses the root domain when it has no conflicting MX, otherwise inbound.<domain>. Returns the MX record the owner must publish; it does not edit DNS.

参数类型必填说明
domain_idstring是域名 ID(以 dom_ 开头),由列表或创建类工具返回。(最多 128 个字符)
返回{domain: 收信域名, status: dns_pending|ready, record: {type: MX, name, value}}。
注解idempotentHint
tools/call 参数示例
{
  "name": "setup_inbound",
  "arguments": {
    "domain_id": "dom_123"
  }
}
改变状态verify_inbound
POST /domains/:domain_id/inbound/verify

验证入站 MX

重新检查入站 MX 记录。当两个公共解析器都能看到该记录时,状态会变为 ready。

参数类型必填说明
domain_idstring是域名 ID(以 dom_ 开头),由列表或创建类工具返回。(最多 128 个字符)
返回{domain, status: ready|dns_pending|propagating|checking, record}。
注解idempotentHint
tools/call 参数示例
{
  "name": "verify_inbound",
  "arguments": {
    "domain_id": "dom_123"
  }
}
只读list_inboxes
GET /inboxes

列出入站地址

列出收件地址,可选择只列出某个域名的地址。结果分页:包含 pagination {offset, limit, returned, total?, has_more, next_offset}。

参数类型必填说明
domain_idstring否可选的域名 ID 筛选条件。
limitinteger否每页条数。默认为 50。(默认 50;1–200)
offsetinteger否要跳过的记录数。请使用上一页返回的 pagination.next_offset。(默认 0;0–…)
返回{data: [{id, address, name, status, domainId}], count, pagination}。
注解readOnlyHint idempotentHint
tools/call 参数示例
{
  "name": "list_inboxes",
  "arguments": {
    "domain_id": "dom_123"
  }
}
只读get_inbox
GET /inboxes/:inbox_id

获取收件箱

获取一个入站地址。

参数类型必填说明
inbox_idstring是收件箱 ID(以 inb_ 开头),由列表或创建类工具返回。(最多 128 个字符)
返回收件箱对象。
注解readOnlyHint idempotentHint
tools/call 参数示例
{
  "name": "get_inbox",
  "arguments": {
    "inbox_id": "inb_123"
  }
}
改变状态create_inbox
POST /inboxes

创建入站地址

在入站状态为 ready 的域名上创建一个地址,例如 support@<receiving domain>(请先运行 setup_inbound 和 verify_inbound)。收到的邮件会出现在 list_emails 中,direction 为 in。

参数类型必填说明
domain_idstring是域名 ID(以 dom_ 开头),由列表或创建类工具返回。(最多 128 个字符)
local_partstring是@ 之前的部分,例如 support。(最多 64 个字符)
namestring否可选的显示名称。
返回{id: inb_…, address, name, status: active}。
tools/call 参数示例
{
  "name": "create_inbox",
  "arguments": {
    "domain_id": "dom_123",
    "local_part": "support",
    "name": "Support"
  }
}
改变状态update_inbox
PATCH /inboxes/:inbox_id

重命名、启用或停用收件箱

重命名收件箱,或将其状态设为 active / disabled。

参数类型必填说明
inbox_idstring是收件箱 ID(以 inb_ 开头),由列表或创建类工具返回。(最多 128 个字符)
namestring否新的显示名称。
statusstring否新状态。(取值为 active、disabled 之一)
返回更新后的收件箱。
注解idempotentHint
tools/call 参数示例
{
  "name": "update_inbox",
  "arguments": {
    "inbox_id": "inb_123",
    "status": "disabled"
  }
}
发送真实邮件set_inbox_forwarding
PUT /inboxes/:inbox_id/forwarding

将收件箱转发到另一个地址

当转发给账户所有者以外的人时,SENDS REAL EMAIL(发送真实邮件):设置收件箱收到的邮件转发到何处。所有者自己的地址会立即生效;其他任何地址都会收到一封确认邮件,在对方确认之前,转发一直处于 pending 状态。传入 forward_to: null 可关闭转发。转发的副本从收件箱地址发出,并将原始发件人设为 Reply-To。

参数类型必填说明
inbox_idstring是收件箱 ID(以 inb_ 开头),由列表或创建类工具返回。(最多 128 个字符)
forward_tostring,null是转发目标邮件地址,或设为 null 以关闭转发。(最多 254 个字符)
返回带有 forwardTo 和 forwardStatus(off、pending 或 active)的收件箱。
注解idempotentHint
tools/call 参数示例
{
  "name": "set_inbox_forwarding",
  "arguments": {
    "inbox_id": "inb_123",
    "forward_to": "team@example.net"
  }
}
破坏性操作delete_inbox
DELETE /inboxes/:inbox_id

删除收件箱

DESTRUCTIVE(破坏性操作):删除一个入站地址。已收到的邮件会保留;发往该地址的新邮件将不再归入其中。

参数类型必填说明
inbox_idstring是收件箱 ID(以 inb_ 开头),由列表或创建类工具返回。(最多 128 个字符)
返回{ok: true}。
注解destructiveHint idempotentHint
tools/call 参数示例
{
  "name": "delete_inbox",
  "arguments": {
    "inbox_id": "inb_123"
  }
}

送达率、退信与抑制记录

只读deliverability_stats
GET /deliverability/stats

获取 30 天投递统计

整个工作区的 30 天汇总:sent、delivery、bounce、complaint、reject、open、click 以及 deliveryRate(%)。

无参数。

返回{window: 30d, sent, delivery, bounce, complaint, reject, open, click, deliveryRate}。
注解readOnlyHint idempotentHint
tools/call 参数示例
{
  "name": "deliverability_stats",
  "arguments": {}
}
Read-onlydeliverability_account
GET /deliverability/account

Get account delivery rates

Daily ladder, today's usage, 7-day hard-bounce and complaint rates against the promote, hold, and pause thresholds, and a per-day trend. Diagnostic text is plain text.

参数类型必填说明
daysinteger否(one of 7, 30, 90)
Returns{days, trend, rolling7d, thresholds, ladder}.
注解readOnlyHint idempotentHint
tools/call 参数示例
{
  "name": "deliverability_account",
  "arguments": {
    "days": 30
  }
}
Read-onlydeliverability_domains
GET /deliverability/domains

Get domain delivery rates

Per sending domain: sent, delivered, hard and soft bounces, complaints, failures, rates, and an active Gmail cap or 4.7.28 backoff when one applies.

参数类型必填说明
daysinteger否
domainstring否
limitinteger否
offsetinteger否
Returns{days, data, count, limit, offset}.
注解readOnlyHint idempotentHint
tools/call 参数示例
{
  "name": "deliverability_domains",
  "arguments": {
    "days": 30
  }
}
Read-onlydeliverability_senders
GET /deliverability/senders

Get sender delivery rates

Per From address: sent, delivered, hard and soft bounces, complaints, failures, and rates.

参数类型必填说明
daysinteger否
domainstring否
limitinteger否
offsetinteger否
Returns{days, data, count, limit, offset}.
注解readOnlyHint idempotentHint
tools/call 参数示例
{
  "name": "deliverability_senders",
  "arguments": {
    "days": 30
  }
}
Read-onlyscore_email
POST /deliverability/score

Score an email's content

A checklist of one email's content before it is sent: 100 for a plain email with no links and no images, lower for each thing mail filters look at (a designed layout, links to another site than the sender's, link shorteners, images with few words, hidden text, capitals, an empty subject, very long HTML). Returns each finding with the points it costs and a one-line suggestion, most points first. Read-only: nothing is stored or sent. Pass the email as written; the unsubscribe footer and tracking SendHQ adds are not scored. It looks at content only: sender reputation, authentication and how recipients react decide more of where mail lands, so treat it as a checklist, not a prediction.

参数类型必填说明
subjectstring否The subject line.
htmlstring否The HTML as written, before SendHQ adds its footer or tracking. (max 2000000 chars)
textstring否The plain-text part. Compared with the HTML when both are given; scored on its own when there is no HTML. (max 2000000 chars)
fromstring否The sender: an email address or a domain such as example.com. Without it, links to other sites are not judged. (max 320 chars)
Returns{score (0 to 100), deductions: [{id, points, count, suggestion}], warnings: [{id, message}]}.
注解readOnlyHint idempotentHint
tools/call 参数示例
{
  "name": "score_email",
  "arguments": {
    "from": "hello@example.com",
    "subject": "Your cart is still here",
    "html": "<p>Pick up where you left off.</p><p><a href=\"https://bit.ly/3xyz\">Finish checkout</a></p>"
  }
}
只读list_sender_reputation
GET /deliverability/reputation

列出发件人信誉

每个具体 From 地址的信誉状态:active、throttled(每日上限降低)或 paused(发送返回 423),并附带原因和每日上限。当发送以 423 或 429 失败时请检查此项。结果分页:包含 pagination {offset, limit, returned, total?, has_more, next_offset}。

参数类型必填说明
limitinteger否每页条数。默认为 50。(默认 50;1–200)
offsetinteger否要跳过的记录数。请使用上一页返回的 pagination.next_offset。(默认 0;0–…)
返回{data: [{sender, status, dailyLimit, reason, cleanSince, warnedAt, pausedAt, evaluatedAt}], count, pagination}。
注解readOnlyHint idempotentHint
tools/call 参数示例
{
  "name": "list_sender_reputation",
  "arguments": {}
}
只读list_suppressions
GET /suppressions

列出抑制记录

工作区抑制列表:在永久性退信或垃圾邮件投诉之后被拦截的收件人。向他们发送会以 422 失败。结果分页:包含 pagination {offset, limit, returned, total?, has_more, next_offset}。

参数类型必填说明
limitinteger否每页条数。默认为 50。(默认 50;1–200)
offsetinteger否要跳过的记录数。请使用上一页返回的 pagination.next_offset。(默认 0;0–…)
返回{data: [{email, reason, detail, created_at}], count, pagination}。
注解readOnlyHint idempotentHint
tools/call 参数示例
{
  "name": "list_suppressions",
  "arguments": {}
}
破坏性操作remove_suppression
DELETE /suppressions/:email

移除退信抑制记录

DESTRUCTIVE(破坏性操作,会削弱一道安全拦截):移除一条退信抑制记录,使该地址可以再次接收邮件。只有在人工确认该地址现已有效时才执行此操作。投诉类抑制记录无法移除(409)。

参数类型必填说明
emailstring是被抑制的收件人地址。(最多 320 个字符)
返回{ok: true}。
注解destructiveHint idempotentHint
tools/call 参数示例
{
  "name": "remove_suppression",
  "arguments": {
    "email": "fixed-mailbox@example.net"
  }
}
只读list_blocked_recipients
GET /blocked-recipients

列出被拦截的收件人

SendHQ 会拒绝发送的所有收件人:退信、投诉以及按域名范围的营销邮件退订,并按类型给出汇总。最多读取最新的 500 条。结果分页:包含 pagination {offset, limit, returned, total?, has_more, next_offset}。

参数类型必填说明
limitinteger否每页条数。默认为 50。(默认 50;1–200)
offsetinteger否要跳过的记录数。请使用上一页返回的 pagination.next_offset。(默认 0;0–…)
返回{data: [{email, domain, kind: bounce|complaint|unsubscribe, reason, detail, source, status, created_at}], count, summary: {total, bounce, complaint, unsubscribe}, pagination}。
注解readOnlyHint idempotentHint
tools/call 参数示例
{
  "name": "list_blocked_recipients",
  "arguments": {}
}

Campaigns

Read-onlylist_contacts
GET /contacts

List contacts

Campaigns: Newest-first contacts with their status, consent evidence, tags, custom fields, engagement (bot-filtered, estimated opens and clicks), and the lists they are subscribed to. Filter by list, status (including dormant), email/name substring (* is an email wildcard, e.g. *@example.com), tag, source, signup date, or a saved segment. Paginated: the result includes pagination {offset, limit, returned, has_more, next_offset}.

参数类型必填说明
list_idstring否Only members of this list (lst_…).
statusstring否Only contacts with this status. dormant: stopped opening and did not answer list cleanup, so broadcasts skip them. (one of subscribed, pending, unsubscribed, bounced, complained, dormant)
querystring否Email or name contains this text; * is a wildcard on the email. (max 200 chars)
tagstring否Only contacts with this tag. (max 60 chars)
sourcestring否How the contact was added. (one of form, api, import)
afterstring否Signed up at or after this time. ISO 8601 date or date-time. (max 40 chars)
beforestring否Signed up before this time. ISO 8601 date or date-time. (max 40 chars)
segment_idstring否Only contacts matching this saved segment (seg_…).
limitinteger否每页条数。默认为 50。(默认 50;1–200)
offsetinteger否要跳过的记录数。请使用上一页返回的 pagination.next_offset。(默认 0;0–…)
Returns{data: [contacts with tags, engagement, dormant, country], count, total, pagination}.
注解readOnlyHint idempotentHint
tools/call 参数示例
{
  "name": "list_contacts",
  "arguments": {
    "status": "subscribed"
  }
}
Changes statecreate_contact
POST /contacts

Add a contact

Campaigns: Add one contact to the workspace, optionally to lists and with tags. A subscribed contact (the default) needs consent_basis: how this person agreed to receive your email. Only add people who asked for your email. Use status: unsubscribed to record an opt-out. Addresses already suppressed or unsubscribed from the workspace are stored with that status. Fails with 409 if the email already exists.

参数类型必填说明
emailstring是Email address. (max 320 chars)
namestring否Display name; the first word is {{first_name}}. (max 200 chars)
fieldsobject否Custom fields (string, number, or boolean values), e.g. {"plan": "pro"}. Usable in broadcasts as {{fields.plan}} or {{plan}}. On update, a null value removes the field.
tagsstring[]否Tags to attach, e.g. ["VIP"]. Up to 50. (0–50 items)
list_idsstring[]否Lists to add the contact to (lst_…). (0–100 items)
statusstring否subscribed (default, requires consent_basis) or unsubscribed. (one of subscribed, unsubscribed)
consent_basisstring否How these people agreed to receive your email, recorded as consent evidence, e.g. Signed up on acme.com/newsletter (double opt-in), exported from Mailchimp. 10-500 characters. (max 500 chars)
ReturnsThe contact.
tools/call 参数示例
{
  "name": "create_contact",
  "arguments": {
    "email": "ada@example.net",
    "name": "Ada Lovelace",
    "consent_basis": "Ticked the newsletter box at checkout on acme.com"
  }
}
Changes stateupsert_contact
PUT /contacts

Create or update a contact by email

Campaigns: Create the contact with this email, or change the one that exists: set name, timezone, and locale, merge fields, and add tags. A new contact needs consent_basis and takes the status its address already has (bounced or complained when suppressed, unsubscribed when it opted out, otherwise subscribed). An existing contact's status is never changed, so nobody is resubscribed. Unlike create_contact it does not fail when the email exists. Automations are enabled workspace by workspace: a workspace that is not enabled gets 403 automations_not_enabled.

参数类型必填说明
emailstring是Email address. (max 320 chars)
namestring否Display name; the first word is {{first_name}}. (max 200 chars)
fieldsobject否Custom fields to merge (string, number, or boolean values), e.g. {"plan": "pro"}. A null value removes a field.
tagsstring[]否Tags to add, e.g. ["VIP"]. Existing tags are kept. (0–50 items)
timezonestring否IANA time zone, e.g. Europe/Paris. Automation emails respect sending hours in this zone. (max 64 chars)
localestring否Language tag, e.g. fr or pt-br. Picks the language version of each automation email. (max 35 chars)
consent_basisstring否How this person agreed to receive your email, e.g. Created an account on acme.com and accepted product emails. Required when the email is not a contact yet. 10-500 characters. (max 500 chars)
ReturnsThe contact, plus timezone, locale, and created (true when it did not exist before).
注解idempotentHint
tools/call 参数示例
{
  "name": "upsert_contact",
  "arguments": {
    "email": "ada@example.net",
    "name": "Ada Lovelace",
    "fields": {
      "plan": "pro"
    },
    "timezone": "Europe/London",
    "consent_basis": "Created an account on acme.com and accepted product emails"
  }
}
Read-onlyget_contact
GET /contacts/:contact_id

Get a contact

Campaigns: One contact by ID or email: status, consent evidence (source, basis, opt-in and confirmation times), custom fields, and subscribed lists.

参数类型必填说明
contact_idstring是Contact ID (starts with ct_) or the contact's email address. (max 320 chars)
ReturnsThe contact.
注解readOnlyHint idempotentHint
tools/call 参数示例
{
  "name": "get_contact",
  "arguments": {
    "contact_id": "ct_123"
  }
}
Changes stateupdate_contact
PATCH /contacts/:contact_id

Update, tag, or unsubscribe a contact

Campaigns: Change a contact's name, merge custom fields (null removes one), change tags (tags replaces the whole set; add_tags and remove_tags change it), or set status to unsubscribed. A contact can never be resubscribed through the API; only the recipient can, by confirming a signup form.

参数类型必填说明
contact_idstring是Contact ID (starts with ct_) or the contact's email address. (max 320 chars)
namestring否New display name. (max 200 chars)
fieldsobject否Custom fields (string, number, or boolean values), e.g. {"plan": "pro"}. Usable in broadcasts as {{fields.plan}} or {{plan}}. On update, a null value removes the field.
tagsstring[]否Replace all of the contact's tags with these. (0–50 items)
add_tagsstring[]否Tags to add. (0–50 items)
remove_tagsstring[]否Tags to remove. (0–50 items)
statusstring否Only unsubscribed is accepted. (one of unsubscribed)
ReturnsThe updated contact.
注解idempotentHint
tools/call 参数示例
{
  "name": "update_contact",
  "arguments": {
    "contact_id": "ct_123",
    "fields": {
      "plan": "team"
    }
  }
}
Destructivedelete_contact
DELETE /contacts/:contact_id

Delete a contact

DESTRUCTIVE: permanently delete a contact and its list memberships. Suppressions and recorded unsubscribes are kept, so the address still cannot be mailed if it is added again. Part of Campaigns.

参数类型必填说明
contact_idstring是Contact ID (starts with ct_) or the contact's email address. (max 320 chars)
返回{ok: true}。
注解destructiveHint idempotentHint
tools/call 参数示例
{
  "name": "delete_contact",
  "arguments": {
    "contact_id": "ct_123"
  }
}
Changes stateimport_contacts
POST /contact-imports

Import contacts from CSV

Campaigns: Import up to 5,000 CSV rows (5 MB) per call, optionally into a list. The header row needs an email column; name (or first_name/last_name), status, and tags (separated by ; or |) are recognized and other columns become custom fields. consent_basis is required and recorded on every new contact. tags are added to every accepted row. Rows whose status says unsubscribed import as unsubscribed; existing contacts keep their status. Returns counts of accepted, created, existing, skipped (duplicates), and invalid rows with line numbers.

参数类型必填说明
csvstring是The CSV file content, header row first. (max 5242880 chars)
list_idstring否Add every accepted row to this list (lst_…).
consent_basisstring是How these people agreed to receive your email, recorded as consent evidence, e.g. Signed up on acme.com/newsletter (double opt-in), exported from Mailchimp. 10-500 characters. (max 500 chars)
tagsstring[]否Tags to add to every accepted row, e.g. ["imported-2026-11"]. (0–50 items)
update_existingboolean否Merge names and fields into contacts that already exist. Their status never changes.
Returns{id, accepted, created, existing, skipped, invalid, errors: [{line, reason}], tags}.
tools/call 参数示例
{
  "name": "import_contacts",
  "arguments": {
    "csv": "email,name\nada@example.net,Ada Lovelace\n",
    "consent_basis": "Newsletter signups exported from Mailchimp (double opt-in)"
  }
}
Read-onlylist_contact_imports
GET /contact-imports

List contact imports

Campaigns: Recent CSV imports with their consent basis and row counts.

参数类型必填说明
limitinteger否每页条数。默认为 50。(默认 50;1–200)
offsetinteger否要跳过的记录数。请使用上一页返回的 pagination.next_offset。(默认 0;0–…)
Returns{data: [imports], count, pagination}.
注解readOnlyHint idempotentHint
tools/call 参数示例
{
  "name": "list_contact_imports",
  "arguments": {}
}
Destructivebulk_update_contacts
POST /contacts/bulk

Bulk update contacts

DESTRUCTIVE when action is delete (permanent) or unsubscribe (cannot be undone through the API). Apply one action to up to 10,000 contacts: the IDs in contact_ids, or everyone matching filter (the list_contacts filters). Actions: tag / untag (with tags), add_to_list / remove_from_list (with list_id), unsubscribe, delete. Adding to a list mirrors each contact's status, so nobody is resubscribed. delete needs confirm_count equal to the number of contacts it would delete: call once without it to get that count (409), confirm with the user, then repeat with it. Part of Campaigns.

参数类型必填说明
actionstring是What to do. (one of tag, untag, add_to_list, remove_from_list, unsubscribe, delete)
contact_idsstring[]否Contact IDs (ct_…). Use this or filter. (0–10000 items)
filterobject否Everyone matching these list_contacts filters. Use this or contact_ids.
filter.list_idstring否Members of this list.
filter.statusstring否Only contacts with this status. dormant: stopped opening and did not answer list cleanup, so broadcasts skip them. (one of subscribed, pending, unsubscribed, bounced, complained, dormant)
filter.querystring否Email or name contains; * is an email wildcard. (max 200 chars)
filter.tagstring否Has this tag. (max 60 chars)
filter.sourcestring否How the contact was added. (one of form, api, import)
filter.afterstring否Signed up at or after. ISO 8601 date or date-time. (max 40 chars)
filter.beforestring否Signed up before. ISO 8601 date or date-time. (max 40 chars)
filter.segment_idstring否Matches this segment.
tagsstring[]否For tag and untag. (0–50 items)
list_idstring否For add_to_list and remove_from_list (lst_…).
confirm_countinteger否For delete: the number of contacts that will be deleted, from the 409 response. (0–…)
Returns{ok, action, count}; for an unconfirmed delete, a 409 error whose message gives the count.
AnnotationsdestructiveHint
tools/call 参数示例
{
  "name": "bulk_update_contacts",
  "arguments": {
    "action": "tag",
    "tags": [
      "october"
    ],
    "filter": {
      "list_id": "lst_123",
      "status": "subscribed"
    }
  }
}
Read-onlylist_tags
GET /tags

List contact tags

Campaigns: The workspace's contact tags, most used first, with how many contacts carry each (up to 500). Paginated.

参数类型必填说明
limitinteger否每页条数。默认为 50。(默认 50;1–200)
offsetinteger否要跳过的记录数。请使用上一页返回的 pagination.next_offset。(默认 0;0–…)
Returns{data: [{tag, count}], count, pagination}.
注解readOnlyHint idempotentHint
tools/call 参数示例
{
  "name": "list_tags",
  "arguments": {}
}
Read-onlylist_contact_fields
GET /contact-fields

List custom contact fields

Campaigns: Defined custom contact fields with label and type (text, number, date). Defined fields are known to check_broadcast's merge-tag check and typed in segment conditions. Contacts may also carry undefined keys. Paginated.

参数类型必填说明
limitinteger否每页条数。默认为 50。(默认 50;1–200)
offsetinteger否要跳过的记录数。请使用上一页返回的 pagination.next_offset。(默认 0;0–…)
Returns{data: [{key, label, type, createdAt}], count, types, pagination}.
注解readOnlyHint idempotentHint
tools/call 参数示例
{
  "name": "list_contact_fields",
  "arguments": {}
}
Changes stateset_contact_field
PUT /contact-fields/:field_key

Define a custom contact field

Campaigns: Create or change a custom field definition (label and type). Values live on each contact's fields. Built-in merge tags (email, name, first_name, last_name, fields, unsubscribe_url) cannot be used as keys. A workspace may define 50 fields.

参数类型必填说明
field_keystring是Field key: a lowercase letter, then up to 39 of a-z, 0-9, and _ (e.g. plan). Used in content as {{fields.plan}}. (max 40 chars)
labelstring否Label shown in the dashboard. Defaults to the key. (max 80 chars)
typestring否text (default), number, or date. (one of text, number, date)
Returns{key, label, type, createdAt}.
注解idempotentHint
tools/call 参数示例
{
  "name": "set_contact_field",
  "arguments": {
    "field_key": "plan",
    "label": "Plan",
    "type": "text"
  }
}
Destructivedelete_contact_field
DELETE /contact-fields/:field_key

Delete a custom field definition

DESTRUCTIVE: delete a custom field definition. Values already stored on contacts are kept. Fails with 404 when the field is not defined. Part of Campaigns.

参数类型必填说明
field_keystring是Field key: a lowercase letter, then up to 39 of a-z, 0-9, and _ (e.g. plan). Used in content as {{fields.plan}}. (max 40 chars)
返回{ok: true}。
注解destructiveHint idempotentHint
tools/call 参数示例
{
  "name": "delete_contact_field",
  "arguments": {
    "field_key": "plan"
  }
}
Read-onlylist_segments
GET /segments

List segments

Campaigns: Saved segments with count (subscribed, non-dormant contacts in the workspace that match now) and fields, the condition fields and operators each accepts. Paginated.

参数类型必填说明
limitinteger否每页条数。默认为 50。(默认 50;1–200)
offsetinteger否要跳过的记录数。请使用上一页返回的 pagination.next_offset。(默认 0;0–…)
Returns{data: [{id, name, match, conditions, count}], count, fields, pagination}.
注解readOnlyHint idempotentHint
tools/call 参数示例
{
  "name": "list_segments",
  "arguments": {}
}
Read-onlyget_segment
GET /segments/:segment_id

Get a segment

Campaigns: One segment with its conditions and live count.

参数类型必填说明
segment_idstring是Segment ID (starts with seg_), as returned by list_segments or create_segment. (max 128 chars)
Returns{id, name, match, conditions, count}.
注解readOnlyHint idempotentHint
tools/call 参数示例
{
  "name": "get_segment",
  "arguments": {
    "segment_id": "seg_123"
  }
}
Read-onlypreview_segment
POST /segments/preview

Preview segment conditions

Campaigns: Count and sample (up to 5) the subscribed, non-dormant contacts that match conditions without saving them. Read-only; use it to check conditions before create_segment.

参数类型必填说明
matchstring否all (default): every condition must match. any: at least one. (one of all, any)
conditionsobject[]否Up to 20 conditions. Opened and clicked use bot-filtered, estimated engagement. (0–20 items)
conditions[].fieldstring是tag, list, status, source, email, name, signed_up, opened, clicked, opens, sends_without_open, country, or a custom field as fields.<key> (or field together with key). (max 48 chars)
conditions[].keystring否Custom field key when field is field. (max 40 chars)
conditions[].opstring是tag: has, not_has. list: in, not_in (a list ID). status: is, is_not (subscribed, pending, unsubscribed, bounced, complained, dormant). source: is, is_not (form, api, import). email: contains, not_contains, ends_with. name: is_set, not_set. signed_up: before, after (YYYY-MM-DD), in_last_days, not_in_last_days. opened / clicked: in_last_days, not_in_last_days, ever, never. opens / sends_without_open: gte, lte. country: is, is_not (two-letter code). Custom fields: equals, not_equals, contains, gt, lt, before, after, is_set, not_set. (one of has, not_has, in, not_in, is, is_not, contains, not_contains, ends_with, is_set, not_set, before, after, in_last_days, not_in_last_days, ever, never, gte, lte, equals, not_equals, gt, lt)
conditions[].valuestring,number否Required except for is_set, not_set, ever, and never. A number of days for in_last_days / not_in_last_days, a number for gte, lte, gt, lt, a date (YYYY-MM-DD) for before / after.
Returns{count, sample: [contacts]}.
注解readOnlyHint idempotentHint
tools/call 参数示例
{
  "name": "preview_segment",
  "arguments": {
    "match": "all",
    "conditions": [
      {
        "field": "tag",
        "op": "has",
        "value": "VIP"
      },
      {
        "field": "opened",
        "op": "in_last_days",
        "value": 90
      }
    ]
  }
}
Changes statecreate_segment
POST /segments

Create a segment

Campaigns: Save a segment: up to 20 conditions joined by match. Use it as a broadcast's audience.segment_id, as list_contacts segment_id, or in bulk_update_contacts filters. A workspace may have 200 segments.

参数类型必填说明
namestring是Segment name. (max 120 chars)
matchstring否all (default): every condition must match. any: at least one. (one of all, any)
conditionsobject[]否Up to 20 conditions. Opened and clicked use bot-filtered, estimated engagement. (0–20 items)
conditions[].fieldstring是tag, list, status, source, email, name, signed_up, opened, clicked, opens, sends_without_open, country, or a custom field as fields.<key> (or field together with key). (max 48 chars)
conditions[].keystring否Custom field key when field is field. (max 40 chars)
conditions[].opstring是tag: has, not_has. list: in, not_in (a list ID). status: is, is_not (subscribed, pending, unsubscribed, bounced, complained, dormant). source: is, is_not (form, api, import). email: contains, not_contains, ends_with. name: is_set, not_set. signed_up: before, after (YYYY-MM-DD), in_last_days, not_in_last_days. opened / clicked: in_last_days, not_in_last_days, ever, never. opens / sends_without_open: gte, lte. country: is, is_not (two-letter code). Custom fields: equals, not_equals, contains, gt, lt, before, after, is_set, not_set. (one of has, not_has, in, not_in, is, is_not, contains, not_contains, ends_with, is_set, not_set, before, after, in_last_days, not_in_last_days, ever, never, gte, lte, equals, not_equals, gt, lt)
conditions[].valuestring,number否Required except for is_set, not_set, ever, and never. A number of days for in_last_days / not_in_last_days, a number for gte, lte, gt, lt, a date (YYYY-MM-DD) for before / after.
ReturnsThe segment with its count.
tools/call 参数示例
{
  "name": "create_segment",
  "arguments": {
    "name": "Engaged pro customers",
    "conditions": [
      {
        "field": "fields.plan",
        "op": "equals",
        "value": "pro"
      },
      {
        "field": "opened",
        "op": "in_last_days",
        "value": 90
      }
    ]
  }
}
Changes stateupdate_segment
PATCH /segments/:segment_id

Update a segment

Campaigns: Rename a segment or change match or conditions (which replaces the whole list). Broadcasts using it pick up the change when they start sending.

参数类型必填说明
segment_idstring是Segment ID (starts with seg_), as returned by list_segments or create_segment. (max 128 chars)
namestring否Segment name. (max 120 chars)
matchstring否all (default): every condition must match. any: at least one. (one of all, any)
conditionsobject[]否Up to 20 conditions. Opened and clicked use bot-filtered, estimated engagement. (0–20 items)
conditions[].fieldstring是tag, list, status, source, email, name, signed_up, opened, clicked, opens, sends_without_open, country, or a custom field as fields.<key> (or field together with key). (max 48 chars)
conditions[].keystring否Custom field key when field is field. (max 40 chars)
conditions[].opstring是tag: has, not_has. list: in, not_in (a list ID). status: is, is_not (subscribed, pending, unsubscribed, bounced, complained, dormant). source: is, is_not (form, api, import). email: contains, not_contains, ends_with. name: is_set, not_set. signed_up: before, after (YYYY-MM-DD), in_last_days, not_in_last_days. opened / clicked: in_last_days, not_in_last_days, ever, never. opens / sends_without_open: gte, lte. country: is, is_not (two-letter code). Custom fields: equals, not_equals, contains, gt, lt, before, after, is_set, not_set. (one of has, not_has, in, not_in, is, is_not, contains, not_contains, ends_with, is_set, not_set, before, after, in_last_days, not_in_last_days, ever, never, gte, lte, equals, not_equals, gt, lt)
conditions[].valuestring,number否Required except for is_set, not_set, ever, and never. A number of days for in_last_days / not_in_last_days, a number for gte, lte, gt, lt, a date (YYYY-MM-DD) for before / after.
ReturnsThe updated segment with its count.
注解idempotentHint
tools/call 参数示例
{
  "name": "update_segment",
  "arguments": {
    "segment_id": "seg_123",
    "name": "Pro customers"
  }
}
Destructivedelete_segment
DELETE /segments/:segment_id

Delete a segment

DESTRUCTIVE: delete a saved segment. Contacts are not affected. Fails with 409 while a sending or scheduled broadcast uses it. Part of Campaigns.

参数类型必填说明
segment_idstring是Segment ID (starts with seg_), as returned by list_segments or create_segment. (max 128 chars)
返回{ok: true}。
注解destructiveHint idempotentHint
tools/call 参数示例
{
  "name": "delete_segment",
  "arguments": {
    "segment_id": "seg_123"
  }
}
Read-onlylist_lists
GET /lists

List contact lists

Campaigns: Contact lists with subscribed, pending, and unsubscribed counts and their hosted signup form settings.

参数类型必填说明
limitinteger否每页条数。默认为 50。(默认 50;1–200)
offsetinteger否要跳过的记录数。请使用上一页返回的 pagination.next_offset。(默认 0;0–…)
Returns{data: [lists], count, pagination}.
注解readOnlyHint idempotentHint
tools/call 参数示例
{
  "name": "list_lists",
  "arguments": {}
}
Changes statecreate_list
POST /lists

Create a list

Campaigns: Create a contact list. Set form_enabled to publish a hosted double opt-in signup form (its URL is in form.url); form_from is the sender, on a verified domain, of the confirmation email, and redirect_url is an optional https page shown after confirming. welcome sends one welcome email when someone confirms. site publishes a public newsletter site at https://sendhq.cc/n/<slug> with the signup form, sent issues, and RSS.

参数类型必填说明
namestring是List name, shown on the signup form. (max 200 chars)
descriptionstring否Short description shown on the signup form. (max 500 chars)
form_enabledboolean否Publish the hosted signup form.
form_fromstring否Sender of signup confirmation emails, e.g. Acme <news@example.com>, on a verified domain. (max 320 chars)
redirect_urlstring否https page to open after a signup is confirmed. (max 500 chars)
welcomeobject否Welcome email sent once, from form_from, when someone confirms a signup. Needs subject and html or markdown when enabled.
welcome.enabledboolean否Send it.
welcome.subjectstring否Subject; merge tags allowed. (max 300 chars)
welcome.htmlstring否HTML body; merge tags allowed. (max 500000 chars)
welcome.markdownstring否Markdown body instead of html, rendered with the workspace design. (max 200000 chars)
siteobject否Public newsletter site at https://sendhq.cc/n/<slug>: a signup form, every issue sent with web.enabled, and an RSS feed at /n/<slug>/feed.xml. Needs the signup form on. A reserved or taken slug fails with 409.
site.enabledboolean否Publish the site.
site.slugstring,null否Address after /n/ (3-48 characters, a-z, 0-9, -). Defaults to the list name. (max 48 chars)
site.titlestring,null否Site title. Defaults to the list name. (max 120 chars)
site.descriptionstring,null否Short description under the title. (max 300 chars)
site.accentstring,null否Accent color, e.g. #0a7d4f.
ReturnsThe list.
tools/call 参数示例
{
  "name": "create_list",
  "arguments": {
    "name": "Product updates"
  }
}
Read-onlyget_list
GET /lists/:list_id

Get a list

Campaigns: One list with member counts and signup form settings.

参数类型必填说明
list_idstring是List ID (starts with lst_), as returned by a list or create tool. (max 128 chars)
ReturnsThe list.
注解readOnlyHint idempotentHint
tools/call 参数示例
{
  "name": "get_list",
  "arguments": {
    "list_id": "lst_123"
  }
}
Changes stateupdate_list
PATCH /lists/:list_id

Update a list

Campaigns: Rename a list, change its description, or change its hosted signup form, welcome email, or newsletter site. Omitted keys inside welcome and site keep their value.

参数类型必填说明
list_idstring是List ID (starts with lst_), as returned by a list or create tool. (max 128 chars)
namestring否New name. (max 200 chars)
descriptionstring否New description. (max 500 chars)
form_enabledboolean否Publish or unpublish the hosted signup form.
form_fromstring否Sender of signup confirmation emails, on a verified domain. (max 320 chars)
redirect_urlstring否https page to open after a signup is confirmed. (max 500 chars)
welcomeobject否Welcome email sent once, from form_from, when someone confirms a signup. Needs subject and html or markdown when enabled.
welcome.enabledboolean否Send it.
welcome.subjectstring否Subject; merge tags allowed. (max 300 chars)
welcome.htmlstring否HTML body; merge tags allowed. (max 500000 chars)
welcome.markdownstring否Markdown body instead of html, rendered with the workspace design. (max 200000 chars)
siteobject否Public newsletter site at https://sendhq.cc/n/<slug>: a signup form, every issue sent with web.enabled, and an RSS feed at /n/<slug>/feed.xml. Needs the signup form on. A reserved or taken slug fails with 409.
site.enabledboolean否Publish the site.
site.slugstring,null否Address after /n/ (3-48 characters, a-z, 0-9, -). Defaults to the list name. (max 48 chars)
site.titlestring,null否Site title. Defaults to the list name. (max 120 chars)
site.descriptionstring,null否Short description under the title. (max 300 chars)
site.accentstring,null否Accent color, e.g. #0a7d4f.
ReturnsThe updated list.
注解idempotentHint
tools/call 参数示例
{
  "name": "update_list",
  "arguments": {
    "list_id": "lst_123",
    "form_enabled": false
  }
}
Destructivedelete_list
DELETE /lists/:list_id

Delete a list

DESTRUCTIVE: delete a list and its memberships. The contacts themselves are kept. Fails with 409 while a broadcast to the list is sending. Part of Campaigns.

参数类型必填说明
list_idstring是List ID (starts with lst_), as returned by a list or create tool. (max 128 chars)
返回{ok: true}。
注解destructiveHint idempotentHint
tools/call 参数示例
{
  "name": "delete_list",
  "arguments": {
    "list_id": "lst_123"
  }
}
Changes stateadd_list_contacts
POST /lists/:list_id/contacts

Add contacts to a list

Campaigns: Add up to 500 existing contacts to a list by ID or email. Subscribed contacts join subscribed; others join in their current state. Unknown references come back in notFound.

参数类型必填说明
list_idstring是List ID (starts with lst_), as returned by a list or create tool. (max 128 chars)
contact_idsstring[]否Contact IDs (ct_…). (0–500 items)
emailsstring[]否Contact email addresses. (0–500 items)
Returns{listId, added, notFound, list}.
注解idempotentHint
tools/call 参数示例
{
  "name": "add_list_contacts",
  "arguments": {
    "list_id": "lst_123",
    "emails": [
      "ada@example.net"
    ]
  }
}
Destructiveremove_list_contact
DELETE /lists/:list_id/contacts/:contact_id

Remove a contact from a list

DESTRUCTIVE: remove one contact from a list. The contact and its status are kept. Part of Campaigns.

参数类型必填说明
list_idstring是List ID (starts with lst_), as returned by a list or create tool. (max 128 chars)
contact_idstring是Contact ID (starts with ct_) or the contact's email address. (max 320 chars)
返回{ok: true}。
注解destructiveHint idempotentHint
tools/call 参数示例
{
  "name": "remove_list_contact",
  "arguments": {
    "list_id": "lst_123",
    "contact_id": "ct_123"
  }
}
Read-onlylist_broadcasts
GET /broadcasts

List broadcasts

Campaigns: Newest-first broadcasts with their status. Paginated: the result includes pagination.

参数类型必填说明
statusstring否Only broadcasts with this status. (one of draft, sending, sent, cancelled, failed)
limitinteger否每页条数。默认为 50。(默认 50;1–200)
offsetinteger否要跳过的记录数。请使用上一页返回的 pagination.next_offset。(默认 0;0–…)
Returns{data: [broadcasts], count, pagination}.
注解readOnlyHint idempotentHint
tools/call 参数示例
{
  "name": "list_broadcasts",
  "arguments": {}
}
Changes statecreate_broadcast
POST /broadcasts

Create a broadcast draft

Campaigns: Create a draft broadcast to one list. Content is html and/or text, markdown, a block document in content, or a published hosted template. Raw content supports merge tags: {{first_name}}, {{name}}, {{email}}, {{fields.plan}}, with fallbacks like {{first_name | there}}. audience narrows it to a segment and/or a number of people (most engaged first with order: engaged); tracking turns open and click tracking off; web publishes it on the list's newsletter site once sent. Nothing is sent until send_broadcast or schedule_broadcast; run check_broadcast and send_broadcast_test first.

参数类型必填说明
namestring否Internal name. Defaults to the subject. (max 200 chars)
list_idstring否The list to send to (lst_…).
fromstring否Sender on a verified domain, e.g. Acme <news@example.com>. (max 320 chars)
reply_tostring否Reply-To address. (max 320 chars)
subjectstring否Subject line; merge tags allowed. (max 998 chars)
preview_textstring否Inbox preview text shown after the subject. (max 300 chars)
htmlstring否HTML body; merge tags allowed and escaped.
textstring否Plain-text body; merge tags allowed.
templateobject否A published hosted template instead of subject/html/text. Template variables are filled from the contact's name, email, and fields.
template.idstring否
template.keystring否
template.version_idstring否
markdownstring否Markdown body instead of html: converted to a block document and rendered with the workspace design (get_newsletter_settings). Merge tags allowed. Not combinable with html or content. (max 1000000 chars)
contentobject,null否Block document ({"type": "doc", "content": [...]}, the dashboard editor's format: paragraph, heading, bulletList, orderedList, blockquote, image, button, callout, horizontalRule, codeBlock). Rendered with the workspace design unless html is also sent.
editorstring否Which editor the dashboard opens: html or blocks. Set automatically for markdown and content. (one of html, blocks)
audienceobject否Who gets it, within the list. Subscribed, non-dormant members only.
audience.segment_idstring,null否Only list members matching this segment (seg_…), or null for the whole list.
audience.orderstring否With a limit: signup (default) or engaged (most engaged first). (one of signup, engaged)
audience.limitinteger,null否Send to at most this many people (send_broadcast_to_more sends to more later), or null for everyone. (1–10000000)
trackingobject否Open and click tracking, both on by default. Opens are estimates (bot-filtered pixel loads), never proof that someone read the email.
tracking.opensboolean否Add an open pixel.
tracking.clicksboolean否Rewrite links to signed SendHQ redirects (the unsubscribe link never is).
webobject否Publish this issue on the list's newsletter site (see create_list site) once it is sent.
web.enabledboolean否Publish it.
web.slugstring,null否Issue address; defaults to the subject. (max 100 chars)
web.pinnedboolean否Keep it at the top of the site.
ReturnsThe draft broadcast.
tools/call 参数示例
{
  "name": "create_broadcast",
  "arguments": {
    "list_id": "lst_123",
    "from": "news@example.com",
    "subject": "October update",
    "markdown": "Hi {{first_name | there}}, here's what shipped.",
    "audience": {
      "order": "engaged",
      "limit": 1000
    }
  }
}
Read-onlyget_broadcast
GET /broadcasts/:broadcast_id

Get a broadcast

Campaigns: One broadcast with its content and, once sending, recipient totals (queued, sending, sent, held, skipped, failed). While a limit or reputation pause holds delivery, lastError explains why and nextAttemptAt says when it resumes.

参数类型必填说明
broadcast_idstring是Broadcast ID (starts with bc_), as returned by a list or create tool. (max 128 chars)
ReturnsThe broadcast.
注解readOnlyHint idempotentHint
tools/call 参数示例
{
  "name": "get_broadcast",
  "arguments": {
    "broadcast_id": "bc_123"
  }
}
Changes stateupdate_broadcast
PATCH /broadcasts/:broadcast_id

Edit a draft broadcast

Campaigns: Change any field of an unscheduled draft broadcast (content, audience, tracking, web). A scheduled draft must be unscheduled first (unschedule_broadcast); sent or sending broadcasts cannot be edited.

参数类型必填说明
broadcast_idstring是Broadcast ID (starts with bc_), as returned by a list or create tool. (max 128 chars)
namestring否Internal name. (max 200 chars)
list_idstring否The list to send to.
fromstring否Sender on a verified domain. (max 320 chars)
reply_tostring否Reply-To address. (max 320 chars)
subjectstring否主题行。(最多 998 个字符)
preview_textstring否Inbox preview text. (max 300 chars)
htmlstring否HTML 正文。
textstring否纯文本正文。
templateobject,null否A published hosted template, or null to remove it.
markdownstring否Markdown body instead of html: converted to a block document and rendered with the workspace design (get_newsletter_settings). Merge tags allowed. Not combinable with html or content. (max 1000000 chars)
contentobject,null否Block document ({"type": "doc", "content": [...]}, the dashboard editor's format: paragraph, heading, bulletList, orderedList, blockquote, image, button, callout, horizontalRule, codeBlock). Rendered with the workspace design unless html is also sent.
editorstring否Which editor the dashboard opens: html or blocks. Set automatically for markdown and content. (one of html, blocks)
audienceobject否Who gets it, within the list. Subscribed, non-dormant members only.
audience.segment_idstring,null否Only list members matching this segment (seg_…), or null for the whole list.
audience.orderstring否With a limit: signup (default) or engaged (most engaged first). (one of signup, engaged)
audience.limitinteger,null否Send to at most this many people (send_broadcast_to_more sends to more later), or null for everyone. (1–10000000)
trackingobject否Open and click tracking, both on by default. Opens are estimates (bot-filtered pixel loads), never proof that someone read the email.
tracking.opensboolean否Add an open pixel.
tracking.clicksboolean否Rewrite links to signed SendHQ redirects (the unsubscribe link never is).
webobject否Publish this issue on the list's newsletter site (see create_list site) once it is sent.
web.enabledboolean否Publish it.
web.slugstring,null否Issue address; defaults to the subject. (max 100 chars)
web.pinnedboolean否Keep it at the top of the site.
ReturnsThe updated draft.
注解idempotentHint
tools/call 参数示例
{
  "name": "update_broadcast",
  "arguments": {
    "broadcast_id": "bc_123",
    "subject": "October product update"
  }
}
Destructivedelete_broadcast
DELETE /broadcasts/:broadcast_id

Delete a draft broadcast

DESTRUCTIVE: permanently delete a draft broadcast. Broadcasts that were sent cannot be deleted. Part of Campaigns.

参数类型必填说明
broadcast_idstring是Broadcast ID (starts with bc_), as returned by a list or create tool. (max 128 chars)
返回{ok: true}。
注解destructiveHint idempotentHint
tools/call 参数示例
{
  "name": "delete_broadcast",
  "arguments": {
    "broadcast_id": "bc_123"
  }
}
Sends real emailsend_broadcast
POST /broadcasts/:broadcast_id/send

Send a broadcast

SENDS REAL EMAIL to the broadcast's audience: every subscribed, non-dormant member of its list, narrowed by its segment and limit. Only call it when the user asked to send this broadcast now. Each message goes through the normal checks (verified domain, marketing plan, suppressions, unsubscribes, reputation, daily and monthly limits) and carries one-click unsubscribe from this list; members that cannot be mailed are skipped. Each contact is sent at most once. Delivery continues in the background: poll get_broadcast for totals and get_broadcast_report for engagement. A scheduled broadcast fails with 409 until unscheduled. Unpaid workspaces (integration trial) can send only to the account email. Pass idempotency_key so a retry cannot start the send twice. Part of Campaigns.

参数类型必填说明
broadcast_idstring是Broadcast ID (starts with bc_), as returned by a list or create tool. (max 128 chars)
idempotency_keystring否Idempotency-Key 请求头(最多 200 个字符)。仅在重试这一完全相同的请求时复用。(最多 200 个字符)
ReturnsThe broadcast with status sending and totals.
tools/call 参数示例
{
  "name": "send_broadcast",
  "arguments": {
    "broadcast_id": "bc_123",
    "idempotency_key": "october-update"
  }
}
Destructivecancel_broadcast
POST /broadcasts/:broadcast_id/cancel

Cancel a broadcast

DESTRUCTIVE: stop a draft or sending broadcast for good. Recipients not yet sent are marked skipped; messages already handed to the provider are not recalled. Part of Campaigns.

参数类型必填说明
broadcast_idstring是Broadcast ID (starts with bc_), as returned by a list or create tool. (max 128 chars)
ReturnsThe cancelled broadcast with totals.
注解destructiveHint idempotentHint
tools/call 参数示例
{
  "name": "cancel_broadcast",
  "arguments": {
    "broadcast_id": "bc_123"
  }
}
Read-onlylist_broadcast_recipients
GET /broadcasts/:broadcast_id/recipients

List broadcast recipients

Campaigns: Per-recipient outcomes and engagement of a broadcast: queued, sending, sent, held, skipped (with the reason), or failed (with the error), the inbox provider, delivered/opened/clicked/bounced/complained/unsubscribed times, and the email ID to inspect delivery events with list_email_events. Filter by outcome, by activity (who opened, clicked, did not open, ...), or by email. Opens are bot-filtered estimates, never proof of reading. Paginated.

参数类型必填说明
broadcast_idstring是Broadcast ID (starts with bc_), as returned by a list or create tool. (max 128 chars)
statusstring否Only recipients with this outcome. (one of queued, sending, sent, held, skipped, failed)
activitystring否Only recipients who did this. (one of opened, clicked, not_opened, not_delivered, bounced, complained, unsubscribed)
querystring否Recipient email contains this text. (max 200 chars)
includestring否links adds the links each recipient clicked (implied by activity: clicked). (one of links)
limitinteger否每页条数。默认为 50。(默认 50;1–200)
offsetinteger否要跳过的记录数。请使用上一页返回的 pagination.next_offset。(默认 0;0–…)
Returns{data: [{contactId, email, status, skipReason, emailId, error, provider, deliveredAt, openedAt, clickedAt, opens, clicks, bouncedAt, complainedAt, unsubscribedAt, links?}], count, totals, pagination}.
注解readOnlyHint idempotentHint
tools/call 参数示例
{
  "name": "list_broadcast_recipients",
  "arguments": {
    "broadcast_id": "bc_123",
    "status": "failed"
  }
}
Read-onlycheck_broadcast
GET /broadcasts/:broadcast_id/checks

Run a broadcast's pre-send checks

Campaigns: The review list shown before sending: sender verification, subject, preview text, content, audience size, size against Gmail's 102 KB clipping limit, postal address, merge tags without data or fallback, empty or shortened links, image descriptions, placeholder text, spam-prone wording, the trial's own-address rule, and whether a test was sent. ready is false while any check has level block; schedule_broadcast refuses then. Fix warn items or tell the user about them.

参数类型必填说明
broadcast_idstring是Broadcast ID (starts with bc_), as returned by a list or create tool. (max 128 chars)
Returns{ready, checks: [{id, level: ok|warn|block, label, detail}], audience: {total, matching}}.
注解readOnlyHint idempotentHint
tools/call 参数示例
{
  "name": "check_broadcast",
  "arguments": {
    "broadcast_id": "bc_123"
  }
}
Sends real emailsend_broadcast_test
POST /broadcasts/:broadcast_id/test

Send a broadcast test

SENDS REAL EMAIL: a copy of the draft marked [Test] to up to 5 addresses (default: the saved test recipients, or the account email), with merge tags filled from contact_id or a sample contact. Never goes to the list. Only send to addresses the user gave or owns. Limited to 100 test sends a day. Template broadcasts are tested with send_template_test. Part of Campaigns.

参数类型必填说明
broadcast_idstring是Broadcast ID (starts with bc_), as returned by a list or create tool. (max 128 chars)
tostring[]否Test recipients (up to 5). (1–5 items)
contact_idstring否Fill merge tags from this contact (ct_…). (max 320 chars)
rememberboolean否Save to as the default test recipients.
Returns{data: [{to, id, status: sent|failed, error?}]}.
tools/call 参数示例
{
  "name": "send_broadcast_test",
  "arguments": {
    "broadcast_id": "bc_123",
    "to": [
      "owner@example.com"
    ]
  }
}
Sends real emailschedule_broadcast
POST /broadcasts/:broadcast_id/schedule

Schedule a broadcast

SENDS REAL EMAIL at scheduled_at to the broadcast's audience, with the same checks as send_broadcast. Only call it when the user asked to send this broadcast at that time. The pre-send checks run now (422 with checks if one blocks). It starts within about a minute of the time; if it can no longer send then, it returns to a draft with the reason in lastError. A scheduled draft cannot be edited until unschedule_broadcast. Part of Campaigns.

参数类型必填说明
broadcast_idstring是Broadcast ID (starts with bc_), as returned by a list or create tool. (max 128 chars)
scheduled_atstring是When to send: ISO 8601 date-time with a timezone, at least a minute and at most a year ahead, e.g. 2026-11-10T09:00:00Z. (max 40 chars)
ReturnsThe broadcast with scheduledAt.
注解idempotentHint
tools/call 参数示例
{
  "name": "schedule_broadcast",
  "arguments": {
    "broadcast_id": "bc_123",
    "scheduled_at": "2026-11-10T09:00:00Z"
  }
}
Changes stateunschedule_broadcast
POST /broadcasts/:broadcast_id/unschedule

Unschedule a broadcast

Campaigns: Return a scheduled broadcast to an editable draft so it does not send. Fails with 409 when it is not scheduled.

参数类型必填说明
broadcast_idstring是Broadcast ID (starts with bc_), as returned by a list or create tool. (max 128 chars)
ReturnsThe draft broadcast.
注解idempotentHint
tools/call 参数示例
{
  "name": "unschedule_broadcast",
  "arguments": {
    "broadcast_id": "bc_123"
  }
}
Changes stateduplicate_broadcast
POST /broadcasts/:broadcast_id/duplicate

Duplicate a broadcast

Campaigns: Copy any broadcast (draft, sent, or cancelled) into a new draft named <name> (copy) with the same list, sender, content, audience, and tracking settings. Nothing is sent.

参数类型必填说明
broadcast_idstring是Broadcast ID (starts with bc_), as returned by a list or create tool. (max 128 chars)
ReturnsThe new draft broadcast.
tools/call 参数示例
{
  "name": "duplicate_broadcast",
  "arguments": {
    "broadcast_id": "bc_123"
  }
}
Sends real emailsend_broadcast_to_more
POST /broadcasts/:broadcast_id/send-more

Send a broadcast to more people

SENDS REAL EMAIL: sends a sent or sending broadcast to up to limit more people in its audience who have not received it (the rest of a limited audience, or people who joined since), in its audience order. Only call it when the user asked for this. Same checks as send_broadcast; each contact still gets it at most once. Fails with 422 when everyone already got it. Pass idempotency_key so a retry cannot add people twice. Part of Campaigns.

参数类型必填说明
broadcast_idstring是Broadcast ID (starts with bc_), as returned by a list or create tool. (max 128 chars)
limitinteger是How many more people at most. (1–10000000)
idempotency_keystring否Idempotency-Key 请求头(最多 200 个字符)。仅在重试这一完全相同的请求时复用。(最多 200 个字符)
Returns{added, broadcast}.
tools/call 参数示例
{
  "name": "send_broadcast_to_more",
  "arguments": {
    "broadcast_id": "bc_123",
    "limit": 500,
    "idempotency_key": "october-update-more-1"
  }
}
Read-onlyget_broadcast_report
GET /broadcasts/:broadcast_id/report

Get a broadcast report

Campaigns: Engagement for a sending or sent broadcast: unique and total opens and clicks, bounces, complaints, and unsubscribes with rates in percent, the same per inbox provider, clicks per link, first opens and clicks by hour, and the average of the previous five broadcasts. Opens are estimates: automated requests (scanners, link previews, privacy prefetching) are counted only in machine. Never claim that a person read the email. Fails with 409 for a draft.

参数类型必填说明
broadcast_idstring是Broadcast ID (starts with bc_), as returned by a list or create tool. (max 128 chars)
Returns{stats: {sent, delivered, opened, clicked, bounced, complained, unsubscribed, opens, clicks, rates}, providers, links, timeline, average, machine, tracking, totals, remaining}.
注解readOnlyHint idempotentHint
tools/call 参数示例
{
  "name": "get_broadcast_report",
  "arguments": {
    "broadcast_id": "bc_123"
  }
}
Read-onlyget_newsletter_settings
GET /newsletter-settings

Get newsletter settings

Campaigns: The postal address added to every marketing email footer, the design (accent color, font, alignment) used for Markdown and block content, list cleanup settings, and default test recipients.

无参数。

Returns{postalAddress, design: {accentColor, font, align}, cleanup: {enabled, afterSends, quietDays, subject, body, from}, testRecipients}.
注解readOnlyHint idempotentHint
tools/call 参数示例
{
  "name": "get_newsletter_settings",
  "arguments": {}
}
Changes stateupdate_newsletter_settings
PATCH /newsletter-settings

Update newsletter settings

Campaigns: Change the postal address (required in marketing email by CAN-SPAM and CASL), design, list cleanup, or default test recipients. Omitted keys keep their value. List cleanup is on by default and sends email automatically: a subscriber who got afterSends broadcasts in a row without opening or clicking and has been quiet for quietDays gets one "still want these?" email; a week later those who did not confirm become dormant (kept, but skipped by broadcasts). Confirm with the user before turning it on or changing its email.

参数类型必填说明
postal_addressstring否Sender's postal address for the footer. Empty string removes it. (max 300 chars)
designobject否Rendering design for Markdown and block content.
design.accentColorstring,null否Hex color like #0a7d4f, or null for the default.
design.fontstring否Font family. (one of sans, serif, mono)
design.alignstring否Text alignment. (one of left, center)
cleanupobject否List cleanup of readers who stopped opening.
cleanup.enabledboolean否Turn list cleanup on or off.
cleanup.afterSendsinteger否Broadcasts in a row without an open or click (3-50). (3–50)
cleanup.quietDaysinteger否Days without engagement (30-730). (30–730)
cleanup.subjectstring,null否Subject of the cleanup email; merge tags allowed. (max 200 chars)
cleanup.bodystring,null否Body text of the cleanup email. (max 2000 chars)
cleanup.fromstring,null否Sender on a verified domain. Defaults to the last sent broadcast's sender. (max 320 chars)
test_recipientsstring[]否Default addresses for send_broadcast_test (up to 5). (0–5 items)
ReturnsThe updated settings.
注解idempotentHint
tools/call 参数示例
{
  "name": "update_newsletter_settings",
  "arguments": {
    "postal_address": "Acme Inc., 1 Main St, Springfield",
    "design": {
      "accentColor": "#0a7d4f"
    }
  }
}
Read-onlyget_campaign_overview
GET /campaigns/overview

Get campaign overview

Campaigns: Subscriber growth and recent results for the last days (7-365, default 30): active, dormant, and pending subscribers, joined and left, a daily series, and the six latest broadcasts with open and click rates (bot-filtered estimates) and their average.

参数类型必填说明
daysinteger否Window in days, 7 to 365. Defaults to 30. (7–365)
Returns{subscribers: {active, dormant, pending, joined, left}, series: [{day, subscribers, joined, left}], recent: [{id, name, subject, status, startedAt, sent, openRate, clickRate}], averages}.
注解readOnlyHint idempotentHint
tools/call 参数示例
{
  "name": "get_campaign_overview",
  "arguments": {
    "days": 30
  }
}
Read-onlylist_uploaded_images
GET /uploads/images

List uploaded images

Campaigns: The workspace's 60 most recent editor image uploads with their public URLs (https://sendhq.cc/i/<id>), to reuse in broadcast HTML, Markdown, or image blocks. Uploading needs the dashboard or the REST API (raw image body). Paginated.

参数类型必填说明
limitinteger否每页条数。默认为 50。(默认 50;1–200)
offsetinteger否要跳过的记录数。请使用上一页返回的 pagination.next_offset。(默认 0;0–…)
Returns{data: [{id, url, width, height, size, filename, createdAt}], pagination}.
注解readOnlyHint idempotentHint
tools/call 参数示例
{
  "name": "list_uploaded_images",
  "arguments": {}
}

Automations, events, and sending limits

Sends real emailtrack_event
POST /events

Record something a contact did

SENDS REAL EMAIL later, when an automation is listening: the contact enters every automation that is on and starts on this event, and that automation then emails them on its schedule, within the workspace's sending limits and hours. Only record what the person really did. In order: the contact changes in contact and the event are saved; open enrolments whose automation names the event as its goal end as converted, and ones that list it as a stop event end; then the contact enters the automations that start on it, unless already in them or reentry forbids it. A contact that is unsubscribed, bounced, or complained is recorded and can leave automations but never enters one. A new contact needs contact.consent_basis. Pass dedupe_key so a retry changes nothing and returns the first result. Automations are enabled workspace by workspace: a workspace that is not enabled gets 403 automations_not_enabled.

参数类型必填说明
emailstring是The contact's email address. (max 320 chars)
eventstring是What they did: a lowercase letter, then a-z, 0-9, and _ (e.g. checkout_started). Names starting email. are reserved. (max 64 chars)
propertiesobject否Up to 50 values (string, number, or boolean; strings are cut at 500 characters), e.g. {"plan": "pro"}. Usable in the automation's emails as merge tags such as {{ plan }}. The names email, name, first_name, last_name, and fields are reserved.
occurred_atstring否When it happened, ISO 8601 with a time zone. Defaults to now; may not be in the future. The automation's emails are timed from it. (max 40 chars)
dedupe_keystring否Stable ID for this event (max 200 chars). A second call with the same key records nothing and returns the first result. (max 200 chars)
contactobject否Changes to the contact, applied with the event.
contact.namestring否Display name. (max 200 chars)
contact.fieldsobject否Custom fields to merge (string, number, or boolean values), e.g. {"plan": "pro"}. A null value removes a field.
contact.timezonestring否IANA time zone, e.g. Europe/Paris. Automation emails respect sending hours in this zone. (max 64 chars)
contact.localestring否Language tag, e.g. fr or pt-br. Picks the language version of each automation email. (max 35 chars)
contact.consent_basisstring否How this person agreed to receive your email, e.g. Created an account on acme.com and accepted product emails. Required when the email is not a contact yet. 10-500 characters. (max 500 chars)
Returns{id, contact_id, started: [automation keys the contact entered], ended: [automation keys the contact left]}.
tools/call 参数示例
{
  "name": "track_event",
  "arguments": {
    "email": "ada@example.net",
    "event": "checkout_started",
    "properties": {
      "plan": "pro"
    },
    "dedupe_key": "checkout_8f3a"
  }
}
Read-onlylist_automations
GET /automations

List automations

Automations: Every automation in priority order with its status (draft, on, or off), how many emails it has, and totals for the last 30 days (entered, sent, delivered, opened, clicked, converted, bounced, complained, unsubscribed, held). held counts each time an email was made to wait by the sending limits, the sending hours, or the automation's daily cap. Each automation carries domain, the domain of its from_address (null while it has no sender). domain narrows the list to the automations that send from one domain (none: those with no sender yet); domains always lists every sender domain of the workspace, in alphabetical order, with how many automations each has. Email bodies are not included; use get_automation. For other date ranges and daily numbers use get_automation_report. Paginated. Automations are enabled workspace by workspace: a workspace that is not enabled gets 403 automations_not_enabled.

参数类型必填说明
domainstring否Only the automations that send from this domain: the exact domain of their from_address (e.g. example.com), or none for automations with no sender yet. (max 253 chars)
limitinteger否每页条数。默认为 50。(默认 50;1–200)
offsetinteger否要跳过的记录数。请使用上一页返回的 pagination.next_offset。(默认 0;0–…)
Returns{data: [{id, key, name, domain, audience_label, goal_label, status, entry, exit_rules, position, settings, from_name, from_address, reply_to, switched_on_at, created_at, updated_at} plus steps_count and totals], count, domains: [{domain, count}], pagination}.
注解readOnlyHint idempotentHint
tools/call 参数示例
{
  "name": "list_automations",
  "arguments": {
    "domain": "example.com"
  }
}
Read-onlyget_automation
GET /automations/:automation_key

Get an automation

Automations: One automation with its emails in order and their language versions, how many people are in it now, and overlap: the other automations that are on and currently have the same people in them, with goes_first true for one that ranks above this automation (the shared people get its emails first and wait in this one). to_fill lists what must still be filled in before it can be turned on: placeholders of the template library left in its emails, and workspace names they print that are blank. Automations are enabled workspace by workspace: a workspace that is not enabled gets 403 automations_not_enabled.

参数类型必填说明
automation_keystring是Automation key, as returned by list_automations (e.g. checkout-recovery). (max 63 chars)
ReturnsThe automation (with domain, the domain of its from_address, or null) with steps (each {id, position, offset_seconds, subject, preheader, editor, content, html, text, skip_if_empty, ignore_send_window, variants}), enrollments {active, waiting}, overlap [{key, name, contacts, position, goes_first}], merge_fields [{key, label}]: the merge tags its emails print, in plain words, and to_fill [{id, position, locale, where, placeholder, key, message}].
注解readOnlyHint idempotentHint
tools/call 参数示例
{
  "name": "get_automation",
  "arguments": {
    "automation_key": "checkout-recovery"
  }
}
Changes statecreate_automation
POST /automations

Create an automation

Automations: Create a timed sequence of emails for one kind of person, as a draft. To start from a ready-made email instead (welcome, onboarding, trial, abandoned checkout, failed payment, winback and more), use use_automation_template. Nothing is sent until set_automation_status turns it on. key is its address and cannot be changed. entry says how people enter, exit_rules when they leave, and steps are the emails, each due offset_seconds after the person entered. from_address must be on a verified domain. Fails with 409 when the key is taken. Automations are enabled workspace by workspace: a workspace that is not enabled gets 403 automations_not_enabled.

参数类型必填说明
keystring是Address of the automation: 1-63 characters of a-z, 0-9, and - (e.g. checkout-recovery). (max 63 chars)
namestring是Name shown in the dashboard. (max 200 chars)
audience_labelstring否Who this is for, in plain words, e.g. Started checkout and left. (max 200 chars)
goal_labelstring否What converting means, in a word or two, e.g. paid. (max 80 chars)
entryobject否How people enter. {type: "event", event} starts on an event recorded with track_event; {type: "manual"} only through enroll_contact. bucket (with segment_id) and date_field (with field) are stored, but nobody enters through them automatically yet. reentry: never (default) or after_end.
entry.typestring是Entry type. (one of event, bucket, date_field, manual)
entry.eventstring否Event name for an event entry, e.g. checkout_started.
entry.segment_idstring否Segment ID (seg_…) for a bucket entry. (max 128 chars)
entry.fieldstring否Contact field key for a date_field entry. (max 40 chars)
entry.reentrystring否Whether someone who finished may enter again. (one of never, after_end)
exit_rulesobject否When people leave. goal_event ends the enrolment as converted and credits the latest email sent within attribution_days before it. Each of stop_events ends it without a conversion. An automation with no goal must say so with no_goal: true. Sent whole: it replaces the current rules.
exit_rules.goal_eventstring,null否Event that counts as converting, e.g. payment_completed.
exit_rules.no_goalboolean否True when this automation deliberately has no goal.
exit_rules.stop_eventsstring[]否Events that take a person out, e.g. ["account_closed"]. (0–20 items)
exit_rules.attribution_daysinteger否Days before the goal within which an email earns the conversion. Default 14. (1–90)
settingsobject否Per-automation settings. Omitted keys keep their value.
settings.exempt_from_holdboolean否Skip the workspace's per-person limits (max_emails and min_gap_hours) for this automation. The sending hours still apply, and its emails still count toward the limits of other automations.
settings.daily_send_capinteger,null否At most this many emails a day from this automation, counted by the day of the workspace's default_timezone; emails over it wait until the next day. null for no cap. (1–…)
settings.daily_entry_capinteger,null否Stored for bucket entries, which are not started automatically yet. It does not limit people entering by event or through enroll_contact. null for no cap. (1–…)
settings.holdout_pctnumber否Percent of people who enter but are sent nothing, to measure what the emails change (0-100). (0–100)
settings.stale_daysinteger否An email more than this many days overdue is skipped instead of sent late. Default 4. (1–365)
settings.resume_after_daysinteger否How long a waiting enrolment waits after the automation ahead of it ends. Default 3. (0–365)
positioninteger否Priority. While one person is in several automations that are on, only the one with the lowest position emails them; the others wait and resume resume_after_days after it ends. (0–100000)
from_namestring否Sender display name, e.g. Acme. (max 120 chars)
from_addressstring否Sender address on a verified workspace domain (see list_sending_identities). (max 320 chars)
reply_tostring否Reply-To address. (max 320 chars)
stepsobject[]否The emails, in order. position defaults to the place in this list. (0–50 items)
steps[].positioninteger否Position of the email in the automation, 1 to 50. (1–50)
steps[].subjectstring否Subject line. Merge tags such as {{ first_name | there }} are filled per contact. (max 998 chars)
steps[].preheaderstring否Inbox preview line. (max 300 chars)
steps[].contentobject否Block document ({type: "doc", content: [...]}), as the dashboard editor stores it. Sent without html, it is rendered with the workspace design. On an email built in the dashboard's drag-and-drop builder (editor design) it is the builder's project instead: opaque, never write one by hand, and send it back only unchanged together with its html.
steps[].htmlstring否HTML body. The unsubscribe footer is added automatically.
steps[].textstring否纯文本正文。
steps[].editorstring否How the email is made: blocks (the dashboard's writing editor, the default), html (your own HTML) or design (the dashboard's drag-and-drop builder). Only the builder makes a design; to send a designed email yourself, send html with editor html. (one of blocks, html, design)
steps[].offset_secondsinteger否When the email is due, in seconds after the moment the person entered (3600 = one hour, 86400 = one day). May be negative for emails that lead up to a date. When several emails are due at once, only the latest is sent and the earlier ones are skipped. (-31622400–31622400)
steps[].skip_if_emptystring[]否Merge keys, e.g. ["fields.plan"]. The email is skipped for a contact where any of them is blank, 0, or false. (0–20 items)
steps[].ignore_send_windowboolean否Send as soon as it is due, outside the workspace's sending hours too. The per-person limits still apply.
ReturnsThe automation with steps (each {id, position, offset_seconds, subject, preheader, editor, content, html, text, skip_if_empty, ignore_send_window, variants}), enrollments {active, waiting}, and overlap [{key, name, contacts}].
tools/call 参数示例
{
  "name": "create_automation",
  "arguments": {
    "key": "checkout-recovery",
    "name": "Checkout recovery",
    "audience_label": "Started checkout and left",
    "goal_label": "paid",
    "from_name": "Acme",
    "from_address": "hello@example.com",
    "entry": {
      "type": "event",
      "event": "checkout_started"
    },
    "exit_rules": {
      "goal_event": "payment_completed"
    },
    "steps": [
      {
        "offset_seconds": 3600,
        "subject": "Still thinking it over, {{ first_name | there }}?",
        "html": "<p>Your cart is waiting.</p>"
      }
    ]
  }
}
Changes stateupdate_automation
PATCH /automations/:automation_key

Edit an automation

Automations: Change an automation's name, labels, entry, exit rules, sender, or priority. settings are merged; entry and exit_rules replace the current ones. The key and the status cannot be changed here (use set_automation_status), and emails are changed with set_automation_step. If the automation is on, the change applies to people in it now, and an edit that would leave it unable to send is refused with 422 automation_not_ready. Automations are enabled workspace by workspace: a workspace that is not enabled gets 403 automations_not_enabled.

参数类型必填说明
automation_keystring是Automation key, as returned by list_automations (e.g. checkout-recovery). (max 63 chars)
namestring否Name shown in the dashboard. (max 200 chars)
audience_labelstring否Who this is for, in plain words, e.g. Started checkout and left. (max 200 chars)
goal_labelstring否What converting means, in a word or two, e.g. paid. (max 80 chars)
entryobject否How people enter. {type: "event", event} starts on an event recorded with track_event; {type: "manual"} only through enroll_contact. bucket (with segment_id) and date_field (with field) are stored, but nobody enters through them automatically yet. reentry: never (default) or after_end.
entry.typestring是Entry type. (one of event, bucket, date_field, manual)
entry.eventstring否Event name for an event entry, e.g. checkout_started.
entry.segment_idstring否Segment ID (seg_…) for a bucket entry. (max 128 chars)
entry.fieldstring否Contact field key for a date_field entry. (max 40 chars)
entry.reentrystring否Whether someone who finished may enter again. (one of never, after_end)
exit_rulesobject否When people leave. goal_event ends the enrolment as converted and credits the latest email sent within attribution_days before it. Each of stop_events ends it without a conversion. An automation with no goal must say so with no_goal: true. Sent whole: it replaces the current rules.
exit_rules.goal_eventstring,null否Event that counts as converting, e.g. payment_completed.
exit_rules.no_goalboolean否True when this automation deliberately has no goal.
exit_rules.stop_eventsstring[]否Events that take a person out, e.g. ["account_closed"]. (0–20 items)
exit_rules.attribution_daysinteger否Days before the goal within which an email earns the conversion. Default 14. (1–90)
settingsobject否Per-automation settings. Omitted keys keep their value.
settings.exempt_from_holdboolean否Skip the workspace's per-person limits (max_emails and min_gap_hours) for this automation. The sending hours still apply, and its emails still count toward the limits of other automations.
settings.daily_send_capinteger,null否At most this many emails a day from this automation, counted by the day of the workspace's default_timezone; emails over it wait until the next day. null for no cap. (1–…)
settings.daily_entry_capinteger,null否Stored for bucket entries, which are not started automatically yet. It does not limit people entering by event or through enroll_contact. null for no cap. (1–…)
settings.holdout_pctnumber否Percent of people who enter but are sent nothing, to measure what the emails change (0-100). (0–100)
settings.stale_daysinteger否An email more than this many days overdue is skipped instead of sent late. Default 4. (1–365)
settings.resume_after_daysinteger否How long a waiting enrolment waits after the automation ahead of it ends. Default 3. (0–365)
positioninteger否Priority. While one person is in several automations that are on, only the one with the lowest position emails them; the others wait and resume resume_after_days after it ends. (0–100000)
from_namestring否Sender display name, e.g. Acme. (max 120 chars)
from_addressstring否Sender address on a verified workspace domain (see list_sending_identities). (max 320 chars)
reply_tostring否Reply-To address. (max 320 chars)
ReturnsThe automation with steps (each {id, position, offset_seconds, subject, preheader, editor, content, html, text, skip_if_empty, ignore_send_window, variants}), enrollments {active, waiting}, and overlap [{key, name, contacts}].
注解idempotentHint
tools/call 参数示例
{
  "name": "update_automation",
  "arguments": {
    "automation_key": "checkout-recovery",
    "name": "Checkout recovery",
    "settings": {
      "holdout_pct": 10
    }
  }
}
Destructivedelete_automation
DELETE /automations/:automation_key

Delete an automation

DESTRUCTIVE: permanently delete an automation with its emails, language versions, enrolments, send records, and statistics. Only a draft or switched-off automation that nobody is currently in can be deleted; otherwise it fails with 409. Confirm with the user first. Automations are enabled workspace by workspace: a workspace that is not enabled gets 403 automations_not_enabled.

参数类型必填说明
automation_keystring是Automation key, as returned by list_automations (e.g. checkout-recovery). (max 63 chars)
返回{ok: true}。
注解destructiveHint idempotentHint
tools/call 参数示例
{
  "name": "delete_automation",
  "arguments": {
    "automation_key": "checkout-recovery"
  }
}
Changes stateset_automation_step
PUT /automations/:automation_key/steps/:position

Create or change an email of an automation

Automations: Create the email at position, or change the fields you pass on the one that is there; fields left out keep their value. If the automation is on, people who have not received this email yet get the new version, so confirm the wording with the user. An existing email keeps its ID: people who already received it are not sent it again. With template, the email becomes that template of the library (see list_automation_templates): its subject, preview text and content replace the email's and its language versions are removed. While the automation is on, an email must keep a subject and content, and may not hold a placeholder of the template library such as [First step] or print a workspace name that is blank (422 automation_not_ready with problems). Automations are enabled workspace by workspace: a workspace that is not enabled gets 403 automations_not_enabled.

参数类型必填说明
automation_keystring是Automation key, as returned by list_automations (e.g. checkout-recovery). (max 63 chars)
positioninteger是Position of the email in the automation, 1 to 50. (1–50)
templatestring否Id of a template of the library, e.g. welcome-note (not a set). The email becomes that template; other fields passed here are applied on top. The email's wait is not the template's: pass offset_seconds. (max 63 chars)
subjectstring否Subject line. Merge tags such as {{ first_name | there }} are filled per contact. (max 998 chars)
preheaderstring否Inbox preview line. (max 300 chars)
contentobject否Block document ({type: "doc", content: [...]}), as the dashboard editor stores it. Sent without html, it is rendered with the workspace design. On an email built in the dashboard's drag-and-drop builder (editor design) it is the builder's project instead: opaque, never write one by hand, and send it back only unchanged together with its html.
htmlstring否HTML body. The unsubscribe footer is added automatically.
textstring否纯文本正文。
editorstring否How the email is made: blocks (the dashboard's writing editor, the default), html (your own HTML) or design (the dashboard's drag-and-drop builder). Only the builder makes a design; to send a designed email yourself, send html with editor html. (one of blocks, html, design)
offset_secondsinteger否When the email is due, in seconds after the moment the person entered (3600 = one hour, 86400 = one day). May be negative for emails that lead up to a date. When several emails are due at once, only the latest is sent and the earlier ones are skipped. (-31622400–31622400)
skip_if_emptystring[]否Merge keys, e.g. ["fields.plan"]. The email is skipped for a contact where any of them is blank, 0, or false. (0–20 items)
ignore_send_windowboolean否Send as soon as it is due, outside the workspace's sending hours too. The per-person limits still apply.
ReturnsThe email: {id, position, offset_seconds, subject, preheader, editor, content, html, text, skip_if_empty, ignore_send_window, variants}.
注解idempotentHint
tools/call 参数示例
{
  "name": "set_automation_step",
  "arguments": {
    "automation_key": "checkout-recovery",
    "position": 2,
    "offset_seconds": 86400,
    "subject": "Your cart is still here",
    "html": "<p>Pick up where you left off.</p>"
  }
}
Destructivedelete_automation_step
DELETE /automations/:automation_key/steps/:position

Remove an email from an automation

DESTRUCTIVE: remove the email at position from an automation. It is no longer sent or listed; records of who already received it are kept. While the automation is on, its only email cannot be removed (409). Confirm with the user first. Automations are enabled workspace by workspace: a workspace that is not enabled gets 403 automations_not_enabled.

参数类型必填说明
automation_keystring是Automation key, as returned by list_automations (e.g. checkout-recovery). (max 63 chars)
positioninteger是Position of the email in the automation, 1 to 50. (1–50)
返回{ok: true}。
注解destructiveHint idempotentHint
tools/call 参数示例
{
  "name": "delete_automation_step",
  "arguments": {
    "automation_key": "checkout-recovery",
    "position": 3
  }
}
Changes stateset_automation_step_variant
PUT /automations/:automation_key/steps/:position/variants/:locale

Create or change a language version of an email

Automations: Save the version of one email for contacts whose locale is this language tag (e.g. fr); a contact with a regional locale such as pt-br gets the pt version when there is no pt-br one. Fields left out keep their value. A version without a body uses the email's own body, and a blank subject or preheader falls back to the email's. Contacts without a matching version get the email as written. If the automation is on, matching contacts who have not received this email yet get this version. While the automation is on, a version may not hold a placeholder of the template library or print a workspace name that is blank (422 automation_not_ready). Automations are enabled workspace by workspace: a workspace that is not enabled gets 403 automations_not_enabled.

参数类型必填说明
automation_keystring是Automation key, as returned by list_automations (e.g. checkout-recovery). (max 63 chars)
positioninteger是Position of the email in the automation, 1 to 50. (1–50)
localestring是Language tag of the version, e.g. fr or pt-br. (max 35 chars)
subjectstring否Subject line. Merge tags such as {{ first_name | there }} are filled per contact. (max 998 chars)
preheaderstring否Inbox preview line. (max 300 chars)
contentobject否Block document ({type: "doc", content: [...]}), as the dashboard editor stores it. Sent without html, it is rendered with the workspace design. On an email built in the dashboard's drag-and-drop builder (editor design) it is the builder's project instead: opaque, never write one by hand, and send it back only unchanged together with its html.
htmlstring否HTML body. The unsubscribe footer is added automatically.
textstring否纯文本正文。
Returns{locale, subject, preheader, content, html, text, updated_at}.
注解idempotentHint
tools/call 参数示例
{
  "name": "set_automation_step_variant",
  "arguments": {
    "automation_key": "checkout-recovery",
    "position": 1,
    "locale": "fr",
    "subject": "Vous hésitez encore ?",
    "html": "<p>Votre panier vous attend.</p>"
  }
}
Sends real emailset_automation_status
POST /automations/:automation_key/status

Turn an automation on or off

SENDS REAL EMAIL when status is on: from then on, everyone who enters the automation is emailed on its schedule, within the workspace's sending limits and hours (get_sending_limits), and people already in it continue. Use preview_automation to see who would get which email. Only turn it on when the user asked for this automation to start. Turning on checks an entry, a goal or exit_rules.no_goal, at least one email with a subject and content, no placeholder of the template library such as [First step] or [Link to plans] left in any email (subject, preview text, body, or a link's address), and no blank workspace name that an email prints (422 automation_not_ready with problems, which names each email and detail; get_automation lists the same under to_fill), a sender on a verified domain (403), and an active subscription (402). off stops new entries and sending; people in it stay and continue if it is turned on again, except that an email more than stale_days overdue by then is skipped. Automations are enabled workspace by workspace: a workspace that is not enabled gets 403 automations_not_enabled.

参数类型必填说明
automation_keystring是Automation key, as returned by list_automations (e.g. checkout-recovery). (max 63 chars)
statusstring是on to start sending, off to stop. (one of on, off)
ReturnsThe automation: {id, key, name, domain, audience_label, goal_label, status, entry, exit_rules, position, settings, from_name, from_address, reply_to, switched_on_at, created_at, updated_at}.
注解idempotentHint
tools/call 参数示例
{
  "name": "set_automation_status",
  "arguments": {
    "automation_key": "checkout-recovery",
    "status": "off"
  }
}
Sends real emailsend_automation_test_email
POST /automations/:automation_key/steps/:position/test

Send one automation email to yourself as a test

SENDS REAL EMAIL: one email of an automation, marked [Test], to the account's own address (get_account -> user.email) and nowhere else; a recipient cannot be given. It is the email as the automation would send it (the language version for locale, the same sender, unsubscribe footer and checks), with stand-in values for its merge tags; sample replaces any of them. A test is not part of the automation: nobody is enrolled, it is in no report, it counts toward nobody's per-person sending limits, it is not tracked, and the automation does not have to be on. It counts toward the workspace's own sending allowance. With dry_run: true nothing is sent and the result is the email as the test would deliver it, with locales and the sample values used. Fails with 422 automation_not_ready when the automation has no sender or the email has no subject or content, and 429 test_limit_reached after 100 test emails in 24 hours. Automations are enabled workspace by workspace: a workspace that is not enabled gets 403 automations_not_enabled.

参数类型必填说明
automation_keystring是Automation key, as returned by list_automations (e.g. checkout-recovery). (max 63 chars)
positioninteger是Position of the email in the automation, 1 to 50. (1–50)
localestring否Send the language version a contact with this language would get (such as fr or pt-br). Omit for the email as written. (max 35 chars)
sampleobject否Values to print for merge tags, by key, in place of the stand-ins (first_name is Alex, and so on). email, product_name, and sender_name cannot be set.
dry_runboolean否Send nothing; return the email as the test would deliver it.
Returns{to, position, locale, subject, id: em_…, status: sent|held}. With dry_run: {dry_run: true, to, from, position, locale, locales, subject, preheader, html, text, sample: [{key, label, value}]}.
tools/call 参数示例
{
  "name": "send_automation_test_email",
  "arguments": {
    "automation_key": "checkout-recovery",
    "position": 1
  }
}
Sends real emailsend_automation_test
POST /automations/:automation_key/test

Send every email of an automation to yourself as tests

SENDS REAL EMAIL: every email of an automation, in order, marked [Test 1 of 3], [Test 2 of 3] and so on, to the account's own address (get_account -> user.email) and nowhere else, without waiting for the emails' delays. Rendering, footer, checks and stand-in values are as in send_automation_test_email. A test is not part of the automation: nobody is enrolled, it is in no report, it counts toward nobody's per-person sending limits, it is not tracked, and the automation does not have to be on. It counts toward the workspace's own sending allowance. Nothing is sent unless everything can be: a sender, a subject and content on every email (422 automation_not_ready with problems), and room for all of them under 100 test emails in 24 hours (429 test_limit_reached). If a send is refused after others went out, the rest are not tried and each email's outcome is returned. Automations are enabled workspace by workspace: a workspace that is not enabled gets 403 automations_not_enabled.

参数类型必填说明
automation_keystring是Automation key, as returned by list_automations (e.g. checkout-recovery). (max 63 chars)
localestring否Send the language version a contact with this language would get (such as fr or pt-br). Omit for the email as written. (max 35 chars)
sampleobject否Values to print for merge tags, by key, in place of the stand-ins (first_name is Alex, and so on). email, product_name, and sender_name cannot be set.
Returns{to, data: [{position, locale, subject, id: em_…, status: sent|held|failed, error?}], count, sent, failed, not_sent}.
tools/call 参数示例
{
  "name": "send_automation_test",
  "arguments": {
    "automation_key": "checkout-recovery"
  }
}
Sends real emailenroll_contact
POST /automations/:automation_key/enroll

Add a contact to an automation

SENDS REAL EMAIL on the automation's schedule: starts the automation for one existing, subscribed contact, counting from anchor_at (now by default). Only call it when the user asked for this person to get this sequence. The automation must be on (409 automation_not_on). Fails with 404 when the email is not a contact (add it with upsert_contact), 422 when the contact cannot be mailed, and 409 when the contact is already in it or went through it before and re-entry is not allowed. Automations are enabled workspace by workspace: a workspace that is not enabled gets 403 automations_not_enabled.

参数类型必填说明
automation_keystring是Automation key, as returned by list_automations (e.g. checkout-recovery). (max 63 chars)
emailstring是Email address of an existing contact. (max 320 chars)
propertiesobject否Up to 50 values (string, number, or boolean; strings are cut at 500 characters), e.g. {"plan": "pro"}. Usable in the automation's emails as merge tags such as {{ plan }}. The names email, name, first_name, last_name, and fields are reserved.
anchor_atstring否The moment the emails' offsets count from, ISO 8601 with a time zone. Defaults to now; may lie ahead for emails that lead up to a date. (max 40 chars)
ReturnsThe enrolment: {id, automation_key, contact_id, status, source, is_holdout, anchor_at, entered_at, next_due_at, exit_reason, ended_at, converted_at}.
tools/call 参数示例
{
  "name": "enroll_contact",
  "arguments": {
    "automation_key": "checkout-recovery",
    "email": "ada@example.net",
    "properties": {
      "plan": "pro"
    }
  }
}
Changes stateexit_contact
POST /automations/:automation_key/exit

Take a contact out of an automation

Automations: End a contact's open enrolment in one automation, so no further emails of it are sent to them. Other automations and broadcasts are not affected, and the contact stays subscribed. Fails with 404 when the contact is not in it. Automations are enabled workspace by workspace: a workspace that is not enabled gets 403 automations_not_enabled.

参数类型必填说明
automation_keystring是Automation key, as returned by list_automations (e.g. checkout-recovery). (max 63 chars)
emailstring是Email address of the contact. (max 320 chars)
reasonstring否Why, for the record (max 200 chars). Defaults to manual. (max 200 chars)
ReturnsThe ended enrolment: {id, automation_key, contact_id, status, source, is_holdout, anchor_at, entered_at, next_due_at, exit_reason, ended_at, converted_at}.
tools/call 参数示例
{
  "name": "exit_contact",
  "arguments": {
    "automation_key": "checkout-recovery",
    "email": "ada@example.net",
    "reason": "Asked support to stop"
  }
}
Read-onlypreview_automation
GET /automations/:automation_key/preview

Preview what an automation would send now

Automations: A dry run. For the people in the automation now, in the order they come due, what would happen if each were evaluated at this moment. outcome is send (the email in step would go out), scheduled (nothing is due before until), held (the email waits until until; reason is limit_cap, limit_gap, window, or daily_cap), waiting (behind the higher-priority automation in behind), skip (reason is stale, empty_field, or holdout), exit (the contact can no longer be mailed and would leave), complete, blocked (automation_off or subscription_required), or in_progress. Read-only: nothing is sent or changed. Use it before set_automation_status, or after changing limits, to see who gets which email. It applies the automation's own rules and does not foresee a refusal only a real send meets, such as the workspace's daily sending limit or a paused sender. Paginated. Automations are enabled workspace by workspace: a workspace that is not enabled gets 403 automations_not_enabled.

参数类型必填说明
automation_keystring是Automation key, as returned by list_automations (e.g. checkout-recovery). (max 63 chars)
limitinteger否每页条数。默认为 50。(默认 50;1–200)
offsetinteger否要跳过的记录数。请使用上一页返回的 pagination.next_offset。(默认 0;0–…)
Returns{automation_key, status, evaluated_at, data: [{enrollment_id, contact_id, email, status, next_due_at, outcome, reason, until, step: {position, subject, locale}, behind: {key, name}, superseded}], count, counts, pagination}.
注解readOnlyHint idempotentHint
tools/call 参数示例
{
  "name": "preview_automation",
  "arguments": {
    "automation_key": "checkout-recovery"
  }
}
Read-onlyget_automations_overview
GET /automations/overview

Get results across all automations

Automations: What every automation of the workspace did in a date range (the last 30 days by default, at most 366 days): totals and one entry per day for people who entered, emails sent, delivered, opened, clicked, and converted (a goal event credited to an email), plus bounces, complaints, unsubscribes, and held (emails made to wait by a limit). Days on which nothing happened are in the series with zeros. domain narrows it to the automations that send from one domain (none: those with no sender yet). Opens and clicks are estimates: each email counts once, at its first open or click by a person, and automated requests (scanners, link previews, privacy prefetching) are never counted. Never claim that a person read an email. Automations are enabled workspace by workspace: a workspace that is not enabled gets 403 automations_not_enabled.

参数类型必填说明
fromstring否First day of the report as a UTC date (YYYY-MM-DD), inclusive.
tostring否Last day of the report as a UTC date (YYYY-MM-DD), inclusive.
domainstring否Only the automations that send from this domain: the exact domain of their from_address (e.g. example.com), or none for automations with no sender yet. (max 253 chars)
Returns{from, to, totals: {entered, sent, delivered, opened, clicked, converted, bounced, complained, unsubscribed, held}, series: [{day, entered, sent, delivered, opened, clicked, converted, bounced, complained, unsubscribed, held}]}.
注解readOnlyHint idempotentHint
tools/call 参数示例
{
  "name": "get_automations_overview",
  "arguments": {
    "from": "2026-10-20",
    "to": "2026-11-18"
  }
}
Read-onlyget_automation_report
GET /automations/:automation_key/report

Get the results of one automation

Automations: The results of one automation in a date range (the last 30 days by default, at most 366 days): the same totals and daily series as get_automations_overview, and steps, one row per email with what it sent and what came of it. An email that was removed is listed with archived: true while it still has numbers in the range. Opens and clicks are estimates: each email counts once, at its first open or click by a person, and automated requests (scanners, link previews, privacy prefetching) are never counted. Never claim that a person read an email. Automations are enabled workspace by workspace: a workspace that is not enabled gets 403 automations_not_enabled.

参数类型必填说明
automation_keystring是Automation key, as returned by list_automations (e.g. checkout-recovery). (max 63 chars)
fromstring否First day of the report as a UTC date (YYYY-MM-DD), inclusive.
tostring否Last day of the report as a UTC date (YYYY-MM-DD), inclusive.
Returns{automation: {key, name, status, goal_label}, from, to, totals, series: [{day, ...}], steps: [{step_id, position, subject, offset_seconds, archived, sent, delivered, opened, clicked, converted, bounced, complained, unsubscribed, held}]}.
注解readOnlyHint idempotentHint
tools/call 参数示例
{
  "name": "get_automation_report",
  "arguments": {
    "automation_key": "checkout-recovery"
  }
}
Read-onlylist_automation_people
GET /automations/:automation_key/people

List the people in an automation

Automations: One row per person who did did in an automation, most recent first: entered (the default: everyone who was ever in it), sent, delivered, opened, clicked, converted (their goal was credited to an email), bounced, unsubscribed, or waiting (waiting now behind a higher-priority automation). step narrows every filter except entered and waiting to one email. Each row has the contact's email and name, when they did it, their enrolment's status, and latest: the most recent thing that happened to them in the automation. counts says how many people each filter would list. Read one person's full history with get_automation_person. Opens and clicks are estimates: each email counts once, at its first open or click by a person, and automated requests (scanners, link previews, privacy prefetching) are never counted. Never claim that a person read an email. Paginated. Automations are enabled workspace by workspace: a workspace that is not enabled gets 403 automations_not_enabled.

参数类型必填说明
automation_keystring是Automation key, as returned by list_automations (e.g. checkout-recovery). (max 63 chars)
didstring否What the people did. Defaults to entered. (one of entered, sent, delivered, opened, clicked, converted, bounced, unsubscribed, waiting)
stepinteger否Only this email of the automation, by its position. (1–50)
limitinteger否每页条数。默认为 50。(默认 50;1–200)
offsetinteger否要跳过的记录数。请使用上一页返回的 pagination.next_offset。(默认 0;0–…)
Returns{automation_key, did, step, data: [{contact_id, email, name, contact_status, enrollment_id, enrollment_status, at, latest: {did, at, step_position, reason}}], count, next_cursor, counts, pagination}.
注解readOnlyHint idempotentHint
tools/call 参数示例
{
  "name": "list_automation_people",
  "arguments": {
    "automation_key": "checkout-recovery",
    "did": "clicked"
  }
}
Read-onlyget_automation_person
GET /automations/:automation_key/people/:contact_id

Get one person's history in an automation

Automations: Everything that happened to one contact in an automation: each enrolment and how it ended, each email with when it was sent, delivered, first opened, first clicked, bounced, complained about, or unsubscribed from, every open and click on it (machine: true marks an automated request, which is not counted), and the conversion with the email it was credited to. Fails with 404 for a contact that was never in the automation. Opens and clicks are estimates: each email counts once, at its first open or click by a person, and automated requests (scanners, link previews, privacy prefetching) are never counted. Never claim that a person read an email. Automations are enabled workspace by workspace: a workspace that is not enabled gets 403 automations_not_enabled.

参数类型必填说明
automation_keystring是Automation key, as returned by list_automations (e.g. checkout-recovery). (max 63 chars)
contact_idstring是Contact ID (starts with ct_) or the contact's email address. (max 320 chars)
Returns{automation_key, contact: {id, email, name, status}, enrollments: [{id, status, source, is_holdout, anchor_at, entered_at, next_due_at, last_sent_at, exit_reason, ended_at, converted_at, converted_send_id}], sends: [{id, enrollment_id, step_id, step_position, subject, status, skip_reason, locale, email_id, sent_at, delivered_at, opened_at, clicked_at, bounced_at, complained_at, unsubscribed_at, converted_at, open_count, machine_open_count, click_count, events: [{kind, machine, reason, position, url, country, at}]}], conversion: {enrollment_id, converted_at, goal_event, send_id, step_position}}.
注解readOnlyHint idempotentHint
tools/call 参数示例
{
  "name": "get_automation_person",
  "arguments": {
    "automation_key": "checkout-recovery",
    "contact_id": "ct_123"
  }
}
Read-onlyget_sending_limits
GET /automation-settings

Get automation sending limits

Automations: How much automation email one person may get across every automation, and when: at most max_emails in any period_days, at least min_gap_hours apart, only between window_start and window_end (hours in the contact's time zone, or default_timezone) on weekdays (0 = Sunday to 6 = Saturday). An email that would break a limit is not dropped: it waits until the limits allow it. Also product_name and sender_name, available to every automation email as merge tags. Automations are enabled workspace by workspace: a workspace that is not enabled gets 403 automations_not_enabled.

无参数。

Returns{max_emails, period_days, min_gap_hours, window_start, window_end, weekdays, default_timezone, product_name, sender_name, updated_at}.
注解readOnlyHint idempotentHint
tools/call 参数示例
{
  "name": "get_sending_limits",
  "arguments": {}
}
Changes stateupdate_sending_limits
PUT /automation-settings

Update automation sending limits

Automations: Change the workspace's per-person limits and sending hours for automation email. Omitted keys keep their value. Looser limits mean people can get more email, sooner: confirm with the user before raising max_emails, shortening min_gap_hours, or widening the hours. product_name and sender_name are the names the emails of the template library print; one that an automation that is on prints cannot be cleared (409 workspace_name_in_use). Automations are enabled workspace by workspace: a workspace that is not enabled gets 403 automations_not_enabled.

参数类型必填说明
max_emailsinteger否Most automation emails one person may get in period_days. Default 2. (1–50)
period_daysinteger否The period max_emails applies to, in days. Default 7. (1–90)
min_gap_hoursinteger否Least time between two automation emails to one person, in hours. Default 44. (0–720)
window_startinteger否First hour of the day emails may go out, local time (0-23). Default 9. (0–23)
window_endinteger否Hour sending stops, local time (1-24); must be later than window_start. Default 18. (1–24)
weekdaysinteger[]否Days emails may go out: 0 = Sunday to 6 = Saturday. Default [1, 2, 3, 4, 5]. (1–7 items)
default_timezonestring否IANA time zone used for contacts that have none, e.g. Europe/London. (max 64 chars)
product_namestring否Your product's name, for {{ product_name }}. (max 120 chars)
sender_namestring否Who the emails are from, for {{ sender_name }}. (max 120 chars)
ReturnsThe updated limits.
注解idempotentHint
tools/call 参数示例
{
  "name": "update_sending_limits",
  "arguments": {
    "max_emails": 3,
    "min_gap_hours": 24,
    "default_timezone": "Europe/London"
  }
}
Read-onlylist_automation_templates
GET /automation-library

List automation templates

Automations: The template library: ready-made lifecycle emails to start an automation from instead of writing one. It covers welcome, onboarding tips, a nudge to finish setup (activation), trial ending and trial ended, abandoned checkout, failed payment (dunning), receipt, upgrade at a usage limit, feature announcement, review request, feedback score (NPS), cancellation survey, and winback for retention. Each template has a name, a one-line purpose, the goal it serves (group), its subject, the merge tags it prints, and start: the suggested entry event, the email's wait, and the goal event that ends the automation for a person. sets are templates that arrive together as one automation: three onboarding tips, trial ending then trial ended, and payment failed then a last notice. fill_in lists what only the user knows: placeholders in square brackets such as [First step] or [Link to plans], and the workspace names the email prints. Email bodies are not included; use get_automation_template. Paginated. Automations are enabled workspace by workspace: a workspace that is not enabled gets 403 automations_not_enabled.

参数类型必填说明
limitinteger否每页条数。默认为 50。(默认 50;1–200)
offsetinteger否要跳过的记录数。请使用上一页返回的 pagination.next_offset。(默认 0;0–…)
Returns{version, groups, data: [{id, kind, name, purpose, group, set, subject, preview_text, needs_consent, start: {entry, offset_seconds, goal_event, goal_label, skip_if_empty}, merge_keys, fill_in: [{kind, key, placeholder, label, example}]}], sets: [{id, kind, name, purpose, group, needs_consent, emails: [{template, offset_seconds}], start, merge_keys, fill_in}], count, pagination}.
注解readOnlyHint idempotentHint
tools/call 参数示例
{
  "name": "list_automation_templates",
  "arguments": {}
}
Read-onlyget_automation_template
GET /automation-library/:template_id

Get an automation template

Automations: One template or one set of the template library, as the draft automation it would make: the suggested start and goal, what the user must fill in, and every email in order with its wait, subject, the email as a block document (content), and preview: the subject and text as this workspace would send them, with sample values for the merge tags. Read it to show the user a welcome, onboarding, trial, abandoned checkout, failed payment (dunning), upgrade, cancellation or winback email before using it. Placeholders such as [First step] are shown as written; a workspace name that is not set reads "Your product" or "Your name" in the preview. Then use_automation_template makes the draft, or set_automation_step with template loads one email into an existing automation. Automations are enabled workspace by workspace: a workspace that is not enabled gets 403 automations_not_enabled.

参数类型必填说明
template_idstring是Id of a template or a set, as returned by list_automation_templates (e.g. welcome-note, checkout-not-finished, payment-failed-notices). (max 63 chars)
Returns{id, kind (email or set), name, purpose, group, set, needs_consent, start: {entry, goal_event, goal_label}, merge_keys, fill_in: [{kind, key, placeholder, label, example}], emails: [{template, name, offset_seconds, skip_if_empty, subject, preview_text, content, preview: {subject, preheader, text, html}}]}. preview.html is null.
注解readOnlyHint idempotentHint
tools/call 参数示例
{
  "name": "get_automation_template",
  "arguments": {
    "template_id": "welcome-note"
  }
}
Changes stateuse_automation_template
POST /automation-library/:template_id/use

Create an automation from a template

Automations: Create a draft automation from a template or a set of the library, ready-made: a welcome email, three onboarding tips, a nudge to finish setup, trial ending and trial ended, abandoned checkout, failed payment (dunning) notices, a receipt, an upgrade email at a usage limit, a feature announcement, a review request, a feedback score, a cancellation survey, or a winback for retention. The draft has the emails, the suggested entry event and the suggested goal. Nothing is sent: it stays a draft until set_automation_status turns it on, and that is refused while anything in to_fill is left. to_fill lists each placeholder to replace, by email (ask the user for the real words and links, then use set_automation_step), and each workspace name the emails print that is blank (product_name, sender_name: set with update_sending_limits). Make sure the entry event is one the workspace records (list_event_names); change the start with update_automation. from_address must be on a verified domain. Fails with 404 for an unknown template and 409 when key is taken. Automations are enabled workspace by workspace: a workspace that is not enabled gets 403 automations_not_enabled.

参数类型必填说明
template_idstring是Id of a template or a set, as returned by list_automation_templates (e.g. welcome-note, checkout-not-finished, payment-failed-notices). (max 63 chars)
keystring否Address of the new automation: 1-63 characters of a-z, 0-9, and -. Defaults to the template's id, with a number added when that is taken. (max 63 chars)
namestring否Name shown in the dashboard. Defaults to the template's own name. (max 200 chars)
from_namestring否Sender display name, e.g. Acme. (max 120 chars)
from_addressstring否Sender address on a verified workspace domain (see list_sending_identities). (max 320 chars)
reply_tostring否Reply-To address. (max 320 chars)
ReturnsThe new automation (status draft) with steps (each {id, position, offset_seconds, subject, preheader, editor, content, html, text, skip_if_empty, ignore_send_window, variants}), merge_fields [{key, label}], template, and to_fill [{id, position, locale, where, placeholder, key, message}]: what must be filled in before it can be turned on.
tools/call 参数示例
{
  "name": "use_automation_template",
  "arguments": {
    "template_id": "welcome-note",
    "name": "Welcome",
    "from_name": "Dana from Acme",
    "from_address": "dana@example.com"
  }
}
Read-onlylist_events
GET /events

List what contacts did

Automations: The events recorded for the workspace, newest first: who (the contact's id, email, and name), what they did (the event name, and the same as words), when, its properties, where it came from (source.type: api for the workspace's own code, connection with the connection's name, upload for a spreadsheet, system for SendHQ itself), and effects: the automations it started, ended, or converted for that contact. Filter by contact (a contact ID or an email address), name (one event name), and from / to. With contact, the result also lists every automation that contact is or was in (enrollments). An event being recorded does not mean an email was sent: check the automation with list_automation_people. Paginated. Automations are enabled workspace by workspace: a workspace that is not enabled gets 403 automations_not_enabled.

参数类型必填说明
contactstring否Only this contact: a contact ID or an email address. (max 320 chars)
namestring否Only this event, e.g. checkout_started. See list_event_names. (max 64 chars)
fromstring否Events from this UTC date (YYYY-MM-DD) or ISO 8601 date-time on. (max 40 chars)
tostring否Events up to this UTC date (the whole day) or ISO 8601 date-time. (max 40 chars)
limitinteger否每页条数。默认为 50。(默认 50;1–200)
offsetinteger否要跳过的记录数。请使用上一页返回的 pagination.next_offset。(默认 0;0–…)
Returns{data: [{id, contact: {id, email, name}, event, words, occurred_at, received_at, source: {type, label, connection_id}, properties, effects: [{did, automation_key, automation_name}]}], count, next_cursor, enrollments (with contact), pagination}.
注解readOnlyHint idempotentHint
tools/call 参数示例
{
  "name": "list_events",
  "arguments": {
    "name": "checkout_started",
    "from": "2026-11-01"
  }
}
Read-onlylist_event_names
GET /events/names

List the kinds of event recorded

Automations: Every distinct event name recorded in the last 30 days with how many times, the most frequent first, each with the name as words (checkout_started reads checkout started). Use it to see what the workspace is being told about before creating an automation that starts on an event. Paginated. Automations are enabled workspace by workspace: a workspace that is not enabled gets 403 automations_not_enabled.

参数类型必填说明
limitinteger否每页条数。默认为 50。(默认 50;1–200)
offsetinteger否要跳过的记录数。请使用上一页返回的 pagination.next_offset。(默认 0;0–…)
Returns{data: [{event, words, count}], count, days, pagination}.
注解readOnlyHint idempotentHint
tools/call 参数示例
{
  "name": "list_event_names",
  "arguments": {}
}
Read-onlylist_connections
GET /connections

List connections

Automations: The workspace's connections. A connection is a secret address another system posts to, such as a payment provider's webhook; what arrives is recorded as events, exactly as track_event records them. Each has its kind (stripe, dodo, or generic), whether it is enabled, whether a signing secret is set, the last four characters of its address, and last_delivery in plain words such as "Recorded 2 events" or "Refused: bad signature". The address and the signing secret are never returned here. Paginated. Automations are enabled workspace by workspace: a workspace that is not enabled gets 403 automations_not_enabled.

参数类型必填说明
limitinteger否每页条数。默认为 50。(默认 50;1–200)
offsetinteger否要跳过的记录数。请使用上一页返回的 pagination.next_offset。(默认 0;0–…)
Returns{data: [{id, name, kind, enabled, event_prefix, consent_basis, has_signing_secret, address_ending, mapping (generic only), created_at, updated_at} plus last_delivery {id, at, result, reason, recorded, events, text, provider_event, email}], count, limit, pagination}.
注解readOnlyHint idempotentHint
tools/call 参数示例
{
  "name": "list_connections",
  "arguments": {}
}
Read-onlyget_connection
GET /connections/:connection_id

Get a connection and its last deliveries

Automations: One connection with its last 50 deliveries, newest first: when each arrived, whether it was recorded, skipped, or refused and why (text says it in plain words), the sender's own event type, the names of the events recorded, and the contact's email address. Payloads are not stored. Use it to find out why something a provider sent did not show up. Automations are enabled workspace by workspace: a workspace that is not enabled gets 403 automations_not_enabled.

参数类型必填说明
connection_idstring是Connection ID, as returned by list_connections (e.g. acn_…). (max 128 chars)
Returns{id, name, kind, enabled, event_prefix, consent_basis, has_signing_secret, address_ending, mapping (generic only), created_at, updated_at} plus last_delivery and deliveries: [{id, at, result, reason, recorded, events, text, provider_event, email}].
注解readOnlyHint idempotentHint
tools/call 参数示例
{
  "name": "get_connection",
  "arguments": {
    "connection_id": "acn_123"
  }
}
Sends real emailcreate_connection
POST /connections

Create a connection

SENDS REAL EMAIL later, when an automation is listening: from the moment the address this returns is given to another system, everything that system posts is recorded as events without anyone looking, and a recorded event starts every automation that is on and starts on it. Only create one when the user asked to connect that system. Returns address once; it cannot be read again, so hand it to the user at once. kind is stripe or dodo (mapped for you: checkout_completed, checkout_abandoned, paid, payment_failed, subscription_started, subscription_renewed, subscription_cancelled, plan_changed) or generic with a mapping. consent_basis is recorded on every contact the connection creates. The provider's signing secret is set by a person in the dashboard or with the REST API, not here. A workspace may have 10 connections (409 connection_limit_reached). Automations are enabled workspace by workspace: a workspace that is not enabled gets 403 automations_not_enabled.

参数类型必填说明
namestring是What to call it, e.g. Stripe. (max 80 chars)
kindstring是stripe, dodo, or generic. (one of generic, stripe, dodo)
consent_basisstring是How the people this connection tells you about agreed to receive your email, e.g. Bought a plan on acme.com and accepted product emails. Recorded on every contact it creates. 10-500 characters. (max 500 chars)
event_prefixstring否Put in front of every event name, e.g. stripe_. (max 32 chars)
enabledboolean否Defaults to true. Pass false to create it switched off.
mappingobject否For a generic connection: dotted paths into the payload it posts, such as customer.email. email is required, and either event or event_name.
mapping.emailstring否Where the contact's email address is. (max 120 chars)
mapping.eventstring否Where the payload names what happened. Order Placed becomes the event order_placed. (max 120 chars)
mapping.event_namestring否One fixed event name, instead of event. (max 64 chars)
mapping.timestring否Where the time it happened is (ISO 8601, or Unix seconds or milliseconds). Defaults to the time of arrival. (max 120 chars)
mapping.idstring否Where a unique ID of the message is, so a retried delivery is recorded once. (max 120 chars)
mapping.keepstring[]否The fields to keep as event properties. Defaults to the top-level text, number, and boolean fields. (0–50 items)
Returns{id, name, kind, enabled, event_prefix, consent_basis, has_signing_secret, address_ending, mapping (generic only), created_at, updated_at} plus address (shown once) and last_delivery: null.
tools/call 参数示例
{
  "name": "create_connection",
  "arguments": {
    "name": "Stripe",
    "kind": "stripe",
    "consent_basis": "Bought a plan on acme.com and accepted product emails"
  }
}
Sends real emailupdate_connection
PATCH /connections/:connection_id

Change a connection or switch it on or off

SENDS REAL EMAIL later when enabled is set to true: what the connected system posts is recorded as events again, and a recorded event starts every automation that is on and starts on it. Only switch one on when the user asked. Also changes name, consent_basis, event_prefix, or a generic connection's mapping. While enabled is false the address answers 404 and records nothing. The kind cannot be changed. Automations are enabled workspace by workspace: a workspace that is not enabled gets 403 automations_not_enabled.

参数类型必填说明
connection_idstring是Connection ID, as returned by list_connections (e.g. acn_…). (max 128 chars)
namestring否A new name. (max 80 chars)
enabledboolean否true: record what arrives. false: answer 404 and record nothing.
consent_basisstring否How the people this connection tells you about agreed to receive your email, e.g. Bought a plan on acme.com and accepted product emails. Recorded on every contact it creates. 10-500 characters. (max 500 chars)
event_prefixstring否Put in front of every event name, e.g. stripe_. (max 32 chars)
mappingobject否For a generic connection: dotted paths into the payload it posts, such as customer.email. email is required, and either event or event_name.
mapping.emailstring否Where the contact's email address is. (max 120 chars)
mapping.eventstring否Where the payload names what happened. Order Placed becomes the event order_placed. (max 120 chars)
mapping.event_namestring否One fixed event name, instead of event. (max 64 chars)
mapping.timestring否Where the time it happened is (ISO 8601, or Unix seconds or milliseconds). Defaults to the time of arrival. (max 120 chars)
mapping.idstring否Where a unique ID of the message is, so a retried delivery is recorded once. (max 120 chars)
mapping.keepstring[]否The fields to keep as event properties. Defaults to the top-level text, number, and boolean fields. (0–50 items)
Returns{id, name, kind, enabled, event_prefix, consent_basis, has_signing_secret, address_ending, mapping (generic only), created_at, updated_at}.
注解idempotentHint
tools/call 参数示例
{
  "name": "update_connection",
  "arguments": {
    "connection_id": "acn_123",
    "enabled": false
  }
}
Destructivedelete_connection
DELETE /connections/:connection_id

Delete a connection

DESTRUCTIVE: permanently delete a connection with its delivery records. Its address stops working at once, so the system that posts to it starts getting 404 and nothing more is recorded from it. The events it already recorded stay. Confirm with the user first; to pause one instead, use update_connection with enabled: false. Automations are enabled workspace by workspace: a workspace that is not enabled gets 403 automations_not_enabled.

参数类型必填说明
connection_idstring是Connection ID, as returned by list_connections (e.g. acn_…). (max 128 chars)
返回{ok: true}。
注解destructiveHint idempotentHint
tools/call 参数示例
{
  "name": "delete_connection",
  "arguments": {
    "connection_id": "acn_123"
  }
}

账户、用量、分析与密钥

只读get_account
GET /account

获取账户、用量与计费信息

账户所有者邮箱、套餐/访问等级、当前周期已用的收件人投递数与配额对比、已用域名数与上限对比、附件传输量、信誉摘要、订阅状态、已公布的套餐以及工作区计数。可用于查看剩余配额,或试用期可以投递给谁(账户邮箱)。

无参数。

返回{user: {email, …}, usage: {domainsUsed, domainLimit, recipientDeliveries, emailQuotaMonth, attachmentBytes, attachmentByteLimit, periodKey}, access: {tier, planCode}, reputation, infrastructure, billing: {status, subscriptions, …}, plans, workspace: {mailer, stats}}。
注解readOnlyHint idempotentHint
tools/call 参数示例
{
  "name": "get_account",
  "arguments": {}
}
Read-onlyget_account_diagnostics
GET /account/diagnostics

Diagnose sending and receiving

One read that explains what is wrong with sending or receiving in this workspace: an issues list (unverified domains and missing DKIM records, inbound MX not ready, paused or throttled senders, quota or daily limit reached, trial restrictions, high bounce or complaint rates, failing webhooks), plan and usage against limits, each domain with its DKIM and inbound state, sending identities, 30-day deliverability and sender reputation, suppressions and unsubscribes, and the last 30 days of messages that were not sent (with reasons) plus bounce, complaint and reject events. Start here when a user asks why mail is not arriving. Never returns message bodies or secrets.

无参数。

Returns{generatedAt, windowDays, issues: [{severity, code, message}], plan: {tier, usage, sendingLimit}, domains: [{name, status, dkim: {required, verified, missing}, inbound}], sendingIdentities, inbound, deliverability: {sent, delivered, bounced, complained, rates, senders}, suppressions: {total, byReason, unsubscribes, recent}, failures: {notSent, recentNotSent, recentProviderEvents}, webhooks}.
注解readOnlyHint idempotentHint
tools/call 参数示例
{
  "name": "get_account_diagnostics",
  "arguments": {}
}
只读get_analytics
GET /analytics

获取发信分析数据

最近 7、30 或 90 天的控制台分析数据:sent/received/delivered/bounced/blocked/opened/clicked/complaint 各项总数、每日时间线、发信量最高的域名以及最常见的主题。

参数类型必填说明
daysinteger否时间窗口(天):7、30(默认)或 90。(取值为 7、30、90 之一)
返回{window, days, metrics, timeline: [{day, sent, received}], domains, topContent}。
注解readOnlyHint idempotentHint
tools/call 参数示例
{
  "name": "get_analytics",
  "arguments": {
    "days": 30
  }
}
只读list_api_keys
GET /keys

列出 API 密钥元数据

列出 API 密钥的名称、非机密前缀和最近使用时间。只读:此 MCP 服务器不能创建、轮换或吊销密钥;这些操作由人在控制台中完成。结果分页:包含 pagination {offset, limit, returned, total?, has_more, next_offset}。

参数类型必填说明
limitinteger否每页条数。默认为 50。(默认 50;1–200)
offsetinteger否要跳过的记录数。请使用上一页返回的 pagination.next_offset。(默认 0;0–…)
返回{data: [{id, name, prefix, lastUsedAt, createdAt}], count, pagination}。
注解readOnlyHint idempotentHint
tools/call 参数示例
{
  "name": "list_api_keys",
  "arguments": {}
}
只读get_service_health
GET /health

检查 SendHQ 服务健康状态

检查 SendHQ API 是否正常运行,以及当前启用的是哪个邮件服务商。不需要有效的 API 密钥。

无参数。

返回{ok, service, mailer}。
注解readOnlyHint idempotentHint
tools/call 参数示例
{
  "name": "get_service_health",
  "arguments": {}
}

API 覆盖清单

公开 API 中的每一项操作,以及覆盖它的工具。用户在控制台中能做且有对应 API 的所有操作都已覆盖;下面列出的排除项是有意为之的。

端点工具备注
POST /emailssend_email发送一封邮件
POST /emails/batchsend_batch发送最多 100 封个性化邮件
GET /emailslist_emails列出已发送和已收到的邮件
GET /emails/:idget_email获取邮件及其附件
PATCH /emails/:idmark_email更新已读、归档、垃圾邮件、分类或重要性状态
POST /emails/:id/labelslabel_email为邮件添加或移除标签
DELETE /emails/:iddelete_email删除已保留的邮件
GET /emails/:id/eventslist_email_events列出某封邮件的投递事件
GET /threads/:idget_thread按时间顺序获取一个会话
GET /labelslist_labels列出标签及其邮件数和归档规则
POST /labelscreate_label创建标签,可同时设置自动归档规则
GET /labels/:idget_label按 ID 或名称获取标签
PATCH /labels/:idupdate_label重命名标签、更改颜色或将其变为分类
DELETE /labels/:iddelete_label删除标签,但不删除其中的邮件
POST /labels/:id/rulescreate_label_rule为标签添加自动归档规则
DELETE /labels/:id/rules/:rule_iddelete_label_rule删除自动归档规则
POST /draftscreate_draft创建撰写草稿
GET /draftslist_drafts列出撰写草稿
GET /drafts/:idget_draft获取草稿及其附件
PUT /drafts/:idupdate_draft替换草稿内容
DELETE /drafts/:iddelete_draft丢弃草稿
POST /drafts/:id/attachmentsupload_attachment向草稿上传附件
GET /attachments/:iddownload_attachment下载私有附件
DELETE /attachments/:iddelete_attachment删除私有附件
GET /sending-identitieslist_sending_identities列出已验证的发信身份
GET /templateslist_templates列出托管模板
POST /templatescreate_template创建托管模板
GET /templates/:idget_template获取草稿、版本和使用情况
PUT /templates/:id/draftupdate_template_draft自动保存模板草稿
POST /templates/:id/draftcreate_template_draft基于已发布版本创建新草稿
POST /templates/:id/renderrender_template渲染与服务端完全一致的输出
POST /templates/:id/testsend_template_test发送测试快照
POST /templates/:id/publishpublish_template发布不可变的模板版本
POST /templates/:id/archivearchive_template归档模板
POST /templates/:id/restorerestore_template恢复已归档的模板
POST /domainsadd_domain添加发信域名
GET /domainslist_domains列出域名及缓存的 DNS 状态
GET /domains/:idget_domain获取域名配置详情
POST /domains/:id/verifyverify_domainRefresh domain and DNS verification
POST /domains/:id/inbound/setupsetup_inboundProvision inbound receiving
POST /domains/:id/inbound/verifyverify_inbound验证入站 MX 路由
DELETE /domains/:iddelete_domain删除域名
GET /dns/providerget_dns_provider检测权威 DNS 服务商及记录的相对主机名
GET /dns/domain-connect/connectget_domain_connect_link创建用于一键配置 DNS 的 Domain Connect 授权链接
POST /inboxescreate_inbox创建入站地址
GET /inboxeslist_inboxes列出入站地址
GET /inboxes/:idget_inbox获取入站地址
PATCH /inboxes/:idupdate_inbox重命名、启用或停用收件箱
PUT /inboxes/:id/forwardingset_inbox_forwarding将收件箱收到的邮件转发到另一个地址
DELETE /inboxes/:iddelete_inbox删除收件箱,同时保留邮件
GET /deliverability/statsdeliverability_stats获取 30 天投递统计
GET /deliverability/reputationlist_sender_reputation按具体发信身份列出信誉状态
GET /deliverability/accountdeliverability_accountAccount delivery rates, daily ladder, and bounce trend
GET /deliverability/domainsdeliverability_domainsPer-domain sent, delivered, hard and soft bounces, complaints, and failures
GET /deliverability/sendersdeliverability_sendersPer-From-address delivery rates
POST /deliverability/scorescore_emailScore an email's content before it is sent
GET /emails/:id/deliveryemail_deliveryDelivery timeline for one email, with bounce and complaint reasons
GET /threads/:id/deliverythread_deliveryPer-thread delivery counts and per-message failure reasons
GET /suppressionslist_suppressions列出工作区的抑制记录
DELETE /suppressions/:emailremove_suppression移除符合条件的退信抑制记录
GET /blocked-recipientslist_blocked_recipients列出退信、投诉和退订
GET /webhooks未开放Webhook endpoints are configured once by a human, in the dashboard or the REST API, and their responses carry signing secrets an agent should not hold. An agent reads the same outcomes with list_email_events, list_emails, and list_blocked_recipients.
POST /webhooks未开放Webhook endpoints are configured once by a human, in the dashboard or the REST API, and their responses carry signing secrets an agent should not hold. An agent reads the same outcomes with list_email_events, list_emails, and list_blocked_recipients.
GET /webhooks/:id未开放Webhook endpoints are configured once by a human, in the dashboard or the REST API, and their responses carry signing secrets an agent should not hold. An agent reads the same outcomes with list_email_events, list_emails, and list_blocked_recipients.
PATCH /webhooks/:id未开放Webhook endpoints are configured once by a human, in the dashboard or the REST API, and their responses carry signing secrets an agent should not hold. An agent reads the same outcomes with list_email_events, list_emails, and list_blocked_recipients.
DELETE /webhooks/:id未开放Webhook endpoints are configured once by a human, in the dashboard or the REST API, and their responses carry signing secrets an agent should not hold. An agent reads the same outcomes with list_email_events, list_emails, and list_blocked_recipients.
POST /webhooks/:id/rotate-secret未开放Webhook endpoints are configured once by a human, in the dashboard or the REST API, and their responses carry signing secrets an agent should not hold. An agent reads the same outcomes with list_email_events, list_emails, and list_blocked_recipients.
POST /webhooks/:id/test未开放Webhook endpoints are configured once by a human, in the dashboard or the REST API, and their responses carry signing secrets an agent should not hold. An agent reads the same outcomes with list_email_events, list_emails, and list_blocked_recipients.
GET /webhooks/:id/deliveries未开放Webhook endpoints are configured once by a human, in the dashboard or the REST API, and their responses carry signing secrets an agent should not hold. An agent reads the same outcomes with list_email_events, list_emails, and list_blocked_recipients.
GET /webhooks/:id/deliveries/:deliveryId未开放Webhook endpoints are configured once by a human, in the dashboard or the REST API, and their responses carry signing secrets an agent should not hold. An agent reads the same outcomes with list_email_events, list_emails, and list_blocked_recipients.
POST /webhooks/:id/deliveries/:deliveryId/retry未开放Webhook endpoints are configured once by a human, in the dashboard or the REST API, and their responses carry signing secrets an agent should not hold. An agent reads the same outcomes with list_email_events, list_emails, and list_blocked_recipients.
GET /contactslist_contactsList contacts
POST /contactscreate_contactAdd a contact with its consent basis
PUT /contactsupsert_contactCreate or update a contact by email
POST /contacts/bulkbulk_update_contactsTag, move, unsubscribe, or delete many contacts at once
GET /contacts/export未开放Image uploads take a raw binary body and the export returns a CSV file meant for a person to download. Agents reuse uploaded images with list_uploaded_images and read the same contacts, filters, tags, and fields as JSON with list_contacts (paginated).
GET /contacts/:idget_contactRetrieve a contact by ID or email
PATCH /contacts/:idupdate_contactUpdate a contact's name, fields, or tags, or unsubscribe it
DELETE /contacts/:iddelete_contactDelete a contact and its list memberships
POST /contact-importsimport_contactsImport contacts from CSV
GET /contact-importslist_contact_importsList recent contact imports
GET /tagslist_tagsList contact tags with how many contacts carry each
GET /contact-fieldslist_contact_fieldsList custom contact field definitions
PUT /contact-fields/:keyset_contact_fieldDefine or change a custom contact field
DELETE /contact-fields/:keydelete_contact_fieldDelete a custom field definition
GET /segmentslist_segmentsList saved segments with live counts
POST /segmentscreate_segmentSave a segment
POST /segments/previewpreview_segmentCount and sample the contacts that match unsaved conditions
GET /segments/:idget_segmentRetrieve a segment and its live count
PATCH /segments/:idupdate_segmentRename a segment or change its conditions
DELETE /segments/:iddelete_segmentDelete a segment
GET /listslist_listsList contact lists with member counts
POST /listscreate_listCreate a list with an optional signup form, welcome email, and newsletter site
GET /lists/:idget_listRetrieve a list
PATCH /lists/:idupdate_listRename a list or change its signup form, welcome email, or site
DELETE /lists/:iddelete_listDelete a list without deleting its contacts
POST /lists/:id/contactsadd_list_contactsAdd existing contacts to a list
DELETE /lists/:id/contacts/:contact_idremove_list_contactRemove a contact from a list
GET /broadcastslist_broadcastsList broadcasts
POST /broadcastscreate_broadcastCreate a broadcast draft
GET /broadcasts/:idget_broadcastRetrieve a broadcast and its delivery totals
PATCH /broadcasts/:idupdate_broadcastEdit a draft broadcast
DELETE /broadcasts/:iddelete_broadcastDelete a draft broadcast
GET /broadcasts/:id/checkscheck_broadcastRun the pre-send checks for a broadcast
POST /broadcasts/:id/testsend_broadcast_testSend a test copy of a draft
POST /broadcasts/:id/scheduleschedule_broadcastSchedule a draft to send later
POST /broadcasts/:id/unscheduleunschedule_broadcastUnschedule a draft
POST /broadcasts/:id/duplicateduplicate_broadcastCopy a broadcast into a new draft
POST /broadcasts/:id/sendsend_broadcastSend a broadcast to its audience
POST /broadcasts/:id/send-moresend_broadcast_to_moreSend a sent broadcast to more of its audience
POST /broadcasts/:id/cancelcancel_broadcastCancel a draft or sending broadcast
GET /broadcasts/:id/recipientslist_broadcast_recipientsList a broadcast's recipients, outcomes, and engagement
GET /broadcasts/:id/reportget_broadcast_reportRetrieve a broadcast's engagement report
GET /campaigns/overviewget_campaign_overviewRetrieve subscriber growth and recent broadcast performance
GET /newsletter-settingsget_newsletter_settingsRetrieve newsletter settings
PATCH /newsletter-settingsupdate_newsletter_settingsChange newsletter settings
POST /uploads/images未开放Image uploads take a raw binary body and the export returns a CSV file meant for a person to download. Agents reuse uploaded images with list_uploaded_images and read the same contacts, filters, tags, and fields as JSON with list_contacts (paginated).
GET /uploads/imageslist_uploaded_imagesList recently uploaded images
POST /eventstrack_eventRecord something a contact did
POST /events/batch未开放History import is a one-time migration step for the account owner and requires a dashboard session. Bulk events are for server-side backfills through the REST API; an agent records what one person did with track_event, which takes a dedupe_key for safe retries.
GET /automationslist_automationsList automations with their 30-day totals
POST /automationscreate_automationCreate an automation as a draft
GET /automations/:keyget_automationRetrieve an automation with its emails
PATCH /automations/:keyupdate_automationEdit an automation
DELETE /automations/:keydelete_automationDelete an automation and its history
PUT /automations/:key/steps/:positionset_automation_stepCreate or change one email of an automation
DELETE /automations/:key/steps/:positiondelete_automation_stepRemove one email from an automation
PUT /automations/:key/steps/:position/variants/:localeset_automation_step_variantCreate or change a language version of an email
POST /automations/:key/steps/:position/testsend_automation_test_emailSend one email of an automation to yourself as a test
POST /automations/:key/testsend_automation_testSend every email of an automation to yourself as tests
POST /automations/:key/statusset_automation_statusTurn an automation on or off
POST /automations/:key/enrollenroll_contactAdd a contact to an automation
POST /automations/:key/exitexit_contactTake a contact out of an automation
GET /automations/:key/previewpreview_automationDry run: what each person in an automation would get now
GET /automations/overviewget_automations_overviewTotals and a daily series across every automation
GET /automations/:key/reportget_automation_reportResults of one automation, with one row per email
GET /automations/:key/peoplelist_automation_peopleList the people in an automation by what they did
GET /automations/:key/people/:contact_idget_automation_personOne person's history in an automation
POST /automations/:key/import-history未开放History import is a one-time migration step for the account owner and requires a dashboard session. Bulk events are for server-side backfills through the REST API; an agent records what one person did with track_event, which takes a dedupe_key for safe retries.
GET /automation-settingsget_sending_limitsRetrieve the workspace's sending limits for automations
PUT /automation-settingsupdate_sending_limitsChange the workspace's sending limits for automations
GET /automation-librarylist_automation_templatesList the template library: ready-made lifecycle emails
GET /automation-library/:idget_automation_templateRead one template or set, with the email as it will look
POST /automation-library/:id/useuse_automation_templateCreate a draft automation from a template or set
GET /eventslist_eventsList what contacts did, newest first
GET /events/nameslist_event_namesList the kinds of event recorded in the last 30 days
POST /events/preview未开放These answer the dashboard's connection and spreadsheet screens and take a request body, while this server keeps its read-only tools to GET. An agent sees what a connection did with get_connection, and what an event started with list_events.
GET /connectionslist_connectionsList the workspace's connections (incoming webhooks)
POST /connectionscreate_connectionCreate a connection and get its address
POST /connections/test未开放These answer the dashboard's connection and spreadsheet screens and take a request body, while this server keeps its read-only tools to GET. An agent sees what a connection did with get_connection, and what an event started with list_events.
GET /connections/:idget_connectionRetrieve a connection with its last deliveries
PATCH /connections/:idupdate_connectionChange a connection or switch it on or off
DELETE /connections/:iddelete_connectionDelete a connection
POST /connections/:id/address未开放The address is a credential: whoever holds it can record events for the workspace. Replacing it cuts off the system that uses the old one, so a person does it in the dashboard, next to that system's own settings.
GET /accountget_account使用 API 密钥获取账户、用量、计费状态和工作区数量
GET /account/diagnosticsget_account_diagnosticsDiagnose sending and receiving problems in the workspace
GET /analyticsget_analytics获取 7 天、30 天或 90 天的控制台发信分析数据
GET /profileget_accountGET /account 的仅限会话版本;MCP 服务器读取的是 API 密钥对应的路由。
POST /billing/checkout未开放按照设计,计费变更仅限会话操作,并且需要账户所有者在控制台中完成。计费状态可通过 get_account 读取。
POST /billing/cancel未开放按照设计,计费变更仅限会话操作,并且需要账户所有者在控制台中完成。计费状态可通过 get_account 读取。
POST /keys未开放有意排除:智能体不得生成或销毁凭据。密钥由人在控制台中管理。
GET /keyslist_api_keys列出 API 密钥元数据
DELETE /keys/:id未开放有意排除:智能体不得生成或销毁凭据。密钥由人在控制台中管理。

有意不提供的功能

功能端点原因
创建、轮换、吊销或删除 API 密钥POST /keys, DELETE /keys/:id有意排除:智能体不得生成或销毁凭据。密钥由人在控制台中管理。
发起结账或取消订阅POST /billing/checkout, POST /billing/cancel按照设计,计费变更仅限会话操作,并且需要账户所有者在控制台中完成。计费状态可通过 get_account 读取。
Cloudflare 一键 DNS 配置(OAuth)GET /api/dns/cloudflare/connect需要交互式浏览器会话和 Cloudflare OAuth 授权。请改用 get_domain 返回的记录、get_dns_provider 返回的主机名或 get_domain_connect_link。
注册、登录、退出登录、关联 Google 账户/api/auth/*面向人的浏览器身份验证;MCP 服务器使用 API 密钥进行身份验证。
联系支持表单POST /api/contact面向人的公开营销网站表单,不属于工作区操作。
Webhook endpoints and deliveriesGET /webhooks, POST /webhooks, GET /webhooks/:id, PATCH /webhooks/:id, DELETE /webhooks/:id, POST /webhooks/:id/rotate-secret, POST /webhooks/:id/test, GET /webhooks/:id/deliveries, GET /webhooks/:id/deliveries/:deliveryId, POST /webhooks/:id/deliveries/:deliveryId/retryWebhook endpoints are configured once by a human, in the dashboard or the REST API, and their responses carry signing secrets an agent should not hold. An agent reads the same outcomes with list_email_events, list_emails, and list_blocked_recipients.
Upload editor images and export contacts as CSVPOST /uploads/images, GET /contacts/exportImage uploads take a raw binary body and the export returns a CSV file meant for a person to download. Agents reuse uploaded images with list_uploaded_images and read the same contacts, filters, tags, and fields as JSON with list_contacts (paginated).
Import an automation's send history and record events in bulkPOST /automations/:key/import-history, POST /events/batchHistory import is a one-time migration step for the account owner and requires a dashboard session. Bulk events are for server-side backfills through the REST API; an agent records what one person did with track_event, which takes a dedupe_key for safe retries.
Move SendHQ's own win-back emails onto automations (backfill and comparison)POST /automations/platform-backfill, GET /automations/platform-compareInternal cutover tools for SendHQ's own workspace only: they answer nobody else, need its owner's dashboard session, and are not part of the public API or of /api/v1. The backfill enrols SendHQ's own accounts, so it is run by a person, one page at a time, after reading the dry run.
Replace a connection's secret addressPOST /connections/:id/addressThe address is a credential: whoever holds it can record events for the workspace. Replacing it cuts off the system that uses the old one, so a person does it in the dashboard, next to that system's own settings.
Dry runs for a sample payload and for a set of eventsPOST /connections/test, POST /events/previewThese answer the dashboard's connection and spreadsheet screens and take a request body, while this server keeps its read-only tools to GET. An agent sees what a connection did with get_connection, and what an event started with list_events.

机器可读的目录:/docs/mcp/tools.json(包含 schema、注解、端点映射和排除项)。本页的 Markdown 版本:/docs/mcp.md。安装 CLI 后,运行 sendhq commands --format json 会输出同一份目录。