Sequenzy Mcp

Sequenzy MCP 服务

Sequenzy 的官方 MCP 服务，这是一款由 AI 驱动的电子邮件营销平台。

将 Sequenzy 连接到 Claude Desktop、Claude Code、Codex、Cursor、Windsurf、VS Code Copilot、OpenClaw 和其他 MCP 客户端，让 AI 助手通过结构化工具管理电子邮件操作，而不是手写 API 调用。

你可以做什么

• 管理订阅者、标签、列表和动态细分，包括批量标签同步和合成事件测试。
• 将细分同步到 Meta 自定义受众，用于 Facebook 和 Instagram 再营销。
• 管理产品，并附加数字交付文件以用于购买自动化。
• 上传托管的电子邮件图片，并设置替代文本和可重复使用的响应式裁剪设置。
• 起草、更新、安排和检查营销活动，包括解析后的受众预览、已保存的转化目标，以及发件人、回复至、抄送和密送身份。
• 将营销活动、序列步骤和模板渲染为精准的、适用于电子邮件的 HTML，而不发送邮件。
• 在电子邮件中添加一键式投票和 NPS 调查区块，并查看营销活动回复摘要。
• 创建和编辑电子邮件序列，包括多列表／标签触发器、受众范围和属性筛选停止条件、发件身份覆盖、现有流程图重组，以及直接向内部审核人员发送步骤测试邮件。
• 取消、暂停、恢复、复制或删除营销活动，并将联系人加入序列。
• 管理事务性电子邮件模板，并向共用的收件人、抄送和密送列表发送事务性电子邮件。
• 提供本地化模板变体，或为已启用的语言区域排队 AI 翻译任务。
• 创建、预览、编辑、发布、取消发布和删除落地页。
• 创建限定列表范围的已保存注册表单，其中包含响应式堆叠、行、网格和 单图片叠加区块组（包括前景间距控件），然后 返回适用于客户端的静态网站嵌入代码。
• 创建、定向、发布、复制和部署已保存的注册弹窗，并使用 相同的递归区块布局。
• 为已发布的落地页连接并验证自定义域名。
• 管理团队邀请、收件箱对话和出站 Webhook 端点。
• 生成电子邮件文案、主题行和多步骤序列。
• 检查分析数据、订阅者活动、送达能力状况、公司级发送暂停、集成、已发布事件的负载架构、发件身份、跟踪设置和控制面板 URL。
• 检查工作区是否显示“Sent with Sequenzy”、所有者订阅为何会或不会移除该标记，并打开规范的订阅页面以升级或续订。权益变更会应用于现有实时序列的后续发送，无需编辑其中的区块。
• 诊断发送暂停的原因，并在确认清理列表后恢复符合条件的硬退信暂停。
• 检查特定收件人的退信、投诉和电子邮件卫生抑制情况，并清理符合条件的陈旧退信，同时不暴露共用的 SES 抑制列表。
• 配置公司产品信息、账户级发送身份默认值，重命名单个发件人和回复至档案，管理发件人域名，并查看常见框架的集成示例。

每个已发布的 MCP 工具都包含明确的 readOnlyHint、destructiveHint 和 openWorldHint 注释，以便兼容的客户端准确显示工具使用方式。工具还会发布 outputSchema 定义并返回 structuredContent，为客户端和模型提供机器可读的结果结构，以便后续调用。

快速设置

最简单的设置方式是使用 Sequenzy 向导：

npx @sequenzy/setup

向导会打开浏览器登录流程、创建个人 API 密钥、检测受支持的 AI 客户端，并在可能时自动为其配置。

托管式远程 MCP

对于支持 Streamable HTTP MCP 的客户端，请使用 Sequenzy 的托管端点，而不是运行本地 stdio 进程：

https://api.sequenzy.com/v1/mcp

ChatGPT 和 OpenAI 插件目录使用经过审核的托管接口：

https://api.sequenzy.com/v1/mcp/openai

该接口共享相同的实现，并保留标准工具集，但以下六项操作除外：connect_integration、create_api_key、create_webhook、list_webhook_deliveries、replay_webhook_delivery 和 rotate_sequence_inbound_webhook_secret。反馈功能仍然可用，但其架构经过精简，仅用于用户明确请求的通用产品反馈。

支持时，远程客户端应使用 Sequenzy OAuth 流程进行身份验证。本地和自动化客户端仍可通过 SEQUENZY_API_KEY 使用下方的 stdio 软件包。

托管端点和 stdio 软件包支持 MCP 规范 2026-07-28，同时兼容 2025 年的客户端。 现代 HTTP 客户端使用逐请求发现和方法标头；现有客户端仍可通过同一端点和软件包命令正常工作。

机器可读的发现文件：

• MCP 服务清单：server.json
• Agent 卡片：.well-known/agent-card.json
• Agent 功能清单：agent-capability.json
• OpenClaw 技能元数据：openclaw/skill.json

数据与隐私

Sequenzy 只会向 MCP 客户端发送运行用户所请求工具所需的数据，且范围仅限于所选工作区以及授予该客户端的密钥或 OAuth 权限范围。根据所请求的工具，这些数据可能包括工作区名称和 ID；订阅者的联系信息、同意信息、受众、属性、事件、互动、回复、调查和商业数据；营销活动和自动化内容；投递分析；以及集成或 webhook 状态。完整的数据类别、用途、接收方、保留期限和用户控制选项，请参阅 Sequenzy 隐私政策。

请勿通过开放式自定义属性、事件、备注、表单、webhook 示例、电子邮件变量或反馈提交支付卡数据、健康或医疗数据、政府颁发的身份标识、生物识别或遗传数据、身份验证凭据、敏感人口统计数据或精确地理位置。

经 OpenAI 审核的接口会针对相关开放式输入声明并强制执行这些限制，包括嵌套属性路径（如 profile.ssn）、坐标对（如 lat/lng）以及带标签的文本（如 宗教：... 或 GPS 坐标：...）。无论凭据位于用户信息、路径、查询还是片段中，只要任何参数包含带凭据的 URL，就会被拒绝，例如带有访问令牌或 URL 签名的表单或弹出窗口 redirectUrl。合并标签中的受限属性选择器会被拒绝，但不会因此拦截关于同一主题的普通撰写内容。在此接口中，render_email 接受示例数据或经过策略检查的内联 subscriber，但不接受 subscriberId，因此无法解析未经检查的已存储自定义属性。其结果会移除受限字段、原始 API 错误、调试负载、内部请求／跟踪／会话标识符、不必要的账户或凭据标识符、已存储的带凭据 URL，以及入站 webhook URL。标准远程 MCP 和本地 stdio 包为受信任的客户端保留完整契约，包括基于凭据的集成设置、一次性 API 密钥和 webhook 密钥、入站 webhook URL 以及详细的 API 错误。如果不希望机密信息出现在 AI 对话中，请优先使用仪表板或本地 CLI。只有在用户明确提出要求时，才会运行 submit_feedback；其 OpenAI 架构仅限于通用消息、类别和可选的工作流上下文，并且接口会拒绝包含电子邮件地址或资源 ID 的反馈文本。

经审核的接口所能保证的范围有限。它会根据数据形态识别受限数据：任意嵌套深度中的英文字段名词语（如 passport_id、user.ssn 或 api_secret）、带标签的文本（如 Diagnosis: ...）、已知的凭据格式、十进制坐标对，以及任何字符串（包括 HTML）中的带凭据 URL。它不会解读未加标签的文本、非英文字段名，或客户端刻意混淆的值；这些仍受上述使用限制约束，而非由过滤器拦截。

手动设置

所有 stdio MCP 客户端使用相同的命令：

• 命令：npx
• 参数：-y @sequenzy/mcp
• 必需的环境变量：SEQUENZY_API_KEY=seq_user_your_key_here

可选环境变量：

• SEQUENZY_API_URL - Sequenzy API 基础 URL。默认为 https://api.sequenzy.com。
• SEQUENZY_APP_URL - 应用 URL 辅助程序使用的 Sequenzy 仪表板基础 URL。默认为 https://sequenzy.com。

Claude Desktop

将以下内容添加到 Claude Desktop 配置中：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "sequenzy": {
      "command": "npx",
      "args": ["-y", "@sequenzy/mcp"],
      "env": {
        "SEQUENZY_API_KEY": "seq_user_your_key_here"
      }
    }
  }
}

编辑配置后，重启 Claude Desktop。

Claude Code

claude mcp add --scope user --env=SEQUENZY_API_KEY=seq_user_your_key_here sequenzy -- npx -y @sequenzy/mcp

在原生 Windows 环境中，请使用 cmd /c 包装 npx：

claude mcp add --scope user --env=SEQUENZY_API_KEY=seq_user_your_key_here sequenzy -- cmd /c npx -y @sequenzy/mcp

要使用共享的项目配置，请使用 .mcp.json：

{
  "mcpServers": {
    "sequenzy": {
      "command": "npx",
      "args": ["-y", "@sequenzy/mcp"],
      "env": {
        "SEQUENZY_API_KEY": "seq_user_your_key_here"
      }
    }
  }
}

Codex

codex mcp add sequenzy --env SEQUENZY_API_KEY=seq_user_your_key_here -- npx -y @sequenzy/mcp
codex mcp list

在 ~/.codex/config.toml 中手动配置 Codex：

[mcp_servers.sequenzy]
command = "npx"
args = ["-y", "@sequenzy/mcp"]

[mcp_servers.sequenzy.env]
SEQUENZY_API_KEY = "seq_user_your_key_here"

Cursor

从 Cursor Marketplace 安装 Sequenzy，通过 Sequenzy OAuth 建立托管连接。该插件连接到：

https://api.sequenzy.com/v1/mcp

安装后，完成浏览器登录流程。之后，Cursor 的 Agent 即可在聊天中使用 Sequenzy 工具，包括选用 Grok 作为模型时。

如需改用手动本地 stdio 配置，请将以下内容添加到 ~/.cursor/mcp.json：

{
  "mcpServers": {
    "sequenzy": {
      "command": "npx",
      "args": ["-y", "@sequenzy/mcp"],
      "env": {
        "SEQUENZY_API_KEY": "seq_user_your_key_here"
      }
    }
  }
}

Windsurf

使用与 Cursor 相同的 JSON 格式。

• macOS：~/Library/Application Support/Windsurf/mcp.json
• Windows：%APPDATA%\Windsurf\mcp.json

VS Code Copilot

VS Code 使用 servers 对象：

{
  "servers": {
    "sequenzy": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@sequenzy/mcp"],
      "env": {
        "SEQUENZY_API_KEY": "seq_user_your_key_here"
      }
    }
  }
}

其他 MCP 客户端

对于 OpenClaw、Hermes 及其他兼容 MCP 的客户端，将客户端指向 npx -y @sequenzy/mcp，并设置 SEQUENZY_API_KEY。

获取 API 密钥

1. 打开 Sequenzy 控制面板。
2. 使用 MCP 设置流程创建个人密钥，或打开 Settings -> API Keys 创建公司密钥。
3. 选择权限预设，或选择集成所需的确切自定义作用域。
4. 将密钥添加到 MCP 客户端配置中。

个人密钥以 seq_user_ 开头。你可以随时在控制面板中撤销这些密钥。

公司密钥也可以在不暴露机密的情况下清理。调用 list_api_keys，查看密钥 ID、名称、非机密前缀、权限、 上次使用时间戳和 isCurrent 标记，然后将确切的 ID 传递给 revoke_api_key。delete_api_key 是执行相同 永久操作的兼容别名。列出和撤销操作的响应中不会包含明文密钥或 存储的密钥哈希。

处理 API 密钥权限缺失

如果工具报告缺少某项权限范围，例如 campaigns:read 或 templates:write，请调用 get_account。它的 apiKeyPermissions 字段会列出 当前密钥的身份和类型、权限范围、常见缺失的营销读取权限范围，以及直接的 manageUrl。经 OpenAI 审核的路径会返回相同的权限信息，但不包含用户的账户 ID 或当前密钥的身份。个人密钥会打开账户 API 密钥页面；公司密钥会打开所选工作区的 API 密钥设置。如果密钥不包含 account:read，请直接打开 Sequenzy 控制面板 并选择对应的 API 密钥页面。

权限可以直接编辑，因此请打开 manageUrl。对于公司密钥，请使用 list_api_keys 及其 isCurrent 标记来识别当前密钥，然后编辑该密钥，再重试失败的工具，无需替换凭据或重启客户端。使用公司密钥且拥有 api_keys:manage 权限的 Agent 也可以改为调用 update_api_key；个人密钥必须在账户级页面上编辑，因为该工具仅管理公司密钥。它的 scopes 和 preset 输入会替换整个权限选择，而不是合并，因此请保留所有仍需使用的现有权限范围。托管式 OAuth 连接也可以通过断开连接并使用更广泛的权限重新授权。

如果当前密钥本身缺少 api_keys:manage，请调用 request_api_key_handoff，而不是重试 update_api_key。它需要 account:read，并会返回一个供所有者审核的 URL，其中已预填请求的密钥名称、权限，以及可选的前序密钥。它绝不会创建或返回密钥；工作区所有者会在浏览器中审核表单、创建替换密钥，并将其复制到客户端。传入 replaceApiKeyId: "current"，即可在创建替换密钥后提供撤销当前密钥的选项。如果当前密钥也缺少 account:read，请直接使用控制面板。

默认的 更安全的 Agent 访问预设包含 lists:write 和 tags:write，因此 Agent 可以创建和更新列表及标签定义；它还包含 subscribers:tag，用于为现有联系人添加标签。它也包含 ab_tests:read、ab_tests:write 和 sequences:write，因此 Agent 可以审核和编辑序列的 A/B 变体文案，包括购物车和浏览放弃消息。它不包含 subscribers:write，因此无法将联系人添加到列表或从列表中移除。删除列表或标签仍需要对应的 lists:delete 或 tags:delete 权限。

AI 起草预设包含 subscribers:write，因此起草 Agent 可以创建列表并向其中添加联系人。应用 listIds 的导入也需要 lists:write；序列订阅或双重选择加入邮件投递还需要 automations:trigger。

工具

标准工具集目前提供 243 个 MCP 工具。经 OpenAI 审核的工具集提供 237 个；仅省略上文列出的六项操作。

工具会拒绝未声明的参数，而不是静默忽略。错误信息会指出不受支持的字段，列出受支持的参数，并针对常见错误提供有针对性的指导，例如虚构的订阅者筛选条件或排序选项。

账户、公司、设置

工具	描述
get_account	获取账户信息、可用公司、当前密钥权限和 API Keys 管理 URL。
select_company	设置后续工具调用所用的当前公司。
get_app_urls	构建活动、落地页、序列、邮件、设置、订阅管理、域名和已发送邮件详情的控制面板 URL。settingsTab: "billing" 会解析为 Account -> Subscription。
create_company	创建新公司或品牌。
get_company	读取公司详情、产品信息、品牌背景、本地化设置、回复跟踪设置、当前默认发件人/回复地址，以及有效的只读 emailBranding 权益（包括套餐/状态原因和订阅 URL）；明确标注 STO 仅适用于活动。
update_company	编辑产品信息、品牌背景、邮件主题、回复跟踪，以及账户级默认发件人/回复地址资料或名称。
get_sync_rules	读取公司的事件到标签规则，以及是否使用继承的平台预设。
update_sync_rules	替换所有同步规则；传入 [] 可禁用规则，传入 null 可启用 SaaS/电商平台预设。
get_shopify_automation_settings	读取已连接 Shopify 商店的浏览放弃、购物车放弃和降价设置。
update_shopify_automation_settings	部分更新 Shopify 自动化设置，或将某个部分重置为平台默认值。
create_api_key	创建公司 API 密钥，并在标准 MCP 中返回一次性密钥；OpenAI 审核路由不提供此工具。
request_api_key_handoff	当当前密钥无法自行管理 API 密钥时，准备由所有者审核的创建/轮换 URL。
list_api_keys	以非机密元数据形式列出公司 API 密钥，以便安全识别和清理。
update_api_key	重命名公司 API 密钥，或替换其权限预设或范围，而不更改密钥值。
revoke_api_key	使用 list_api_keys 检查后，按 ID 永久撤销指定的公司 API 密钥。
delete_api_key	revoke_api_key 的兼容性别名。
list_websites	列出发送域名及已存储的汇总、SPF、DKIM 和 MAIL FROM 状态。
add_sending_domain	添加发送域名，并返回该群组专属的 DNS 设置记录。
add_website	add_sending_domain 的兼容性别名。
check_website	读取发送域名已存储的 SPF、DKIM、MAIL FROM 和汇总验证详情。
verify_sending_domain	重新运行发送域名 DNS/提供商验证，并返回当前状态和诊断信息。
list_integrations	列出已连接的集成及其连接和同步健康状况，不返回凭据。
get_sending_status	诊断发送处于活动、暂停或挂起状态的原因，包括执行阈值分母、审核关卡和补救步骤。
resume_sending	在明确确认列表已清理后，恢复符合条件的硬退信暂停状态。
get_tracking_settings	读取账户级和 Transactional API 的打开/点击默认设置、取消订阅、归因、UTM、点击域名、回复跟踪和双重确认订阅设置。
update_tracking_settings	更新账户级和 Transactional API 跟踪默认设置、归因、UTM，以及账户级双重确认订阅设置。
get_integration_guide	获取特定框架的集成示例。
get_integration	检查一个已连接的集成，包括其事件接线、列表定向、近期活动和建议。
list_integration_capabilities	比较提供商的功能，无论是否已连接。
connect_integration	在标准 MCP 中连接支持 API 密钥或 Webhook 密钥的提供商，包括托管式 Lemon Squeezy Webhook、仅出站的 Attio，以及可选的 PostHog/Segment 历史记录导入；OpenAI 审核路由不提供此工具。
get_event_schema	按提供商检查已发布的事件载荷示例、属性路径、类型和合并标签。
list_integration_activity	读取保留的集成专属 Webhook 和同步活动日志。
set_integration_sync_enabled	启用或禁用批量导入和回填，同时保持实时 Webhook 连接。
set_integration_list_targeting	选择未来由提供商写入数据时，受支持集成创建的联系人应加入哪些列表。
sync_integration	使用已保存的集成配置，排队同步支付收入、Supabase 用户或 PostHog/Segment 事件历史记录导入。
get_integration_pixel	读取 Shopify 的实时像素/配置状态，并区分已确认的暗事件与未知读取结果。
activate_integration_pixel	安装或重新指向 Shopify 店面像素；若像素已是最新状态，则不会产生额外影响。
list_web_tracking_keys	列出可公开的网页跟踪密钥、来源限制、使用状态和安装代码片段。
get_web_tracking_key	获取一个网页跟踪密钥及其确切安装代码片段和数据接收端点。
create_web_tracking_key	为非 Shopify 店面或网站创建可公开的跟踪密钥。
update_web_tracking_key	重命名、限制、撤销或重新启用网页跟踪密钥。
delete_web_tracking_key	移除代码片段后，永久删除网页跟踪密钥。
list_sender_profiles	列出发件人和回复地址资料、默认设置及发送域名就绪状态。
update_sender_profile	重命名一个发件人或回复地址资料，而不更改账户默认设置。
delete_sender_profile	永久删除未使用的发件人资料，并防止删除仍用于实时发送界面或最后一个剩余发件人的资料。
get_notification_preferences	读取当前用户按公司区分的账户通知设置和支持的模式，包括周一周报。
update_notification_preferences	更新当前用户的账户通知发送模式，包括退出周报，不影响团队成员。
render_email	呈现最终可安全用于邮件的 HTML，并诊断未解析的合并标签，包括被默认值隐藏的拼写错误。OpenAI 审核路由接受示例数据或通过策略检查的内联订阅者，而不接受已存储的订阅者 ID。
get_sending_status 会在发件人健康分析暂时不可用时，继续提供由 Postgres 支持的暂停状态、审核关卡和补救措施；在这种降级情况下，senderHealth 为 null。

render_email 会返回 unresolvedMergeTags，让调用方区分未知名称与已识别但对预览联系人而言为空的标签。即使 default 过滤器提供了文本，系统也会报告未知名称：例如，{{ subscriber.frstName | default: "there" }} 会为每位联系人渲染出看似合理的问候语，同时绕过已存储的名字。对于某位联系人为空的已识别名称，如果使用了默认值，则不会报告。经 OpenAI 审核的路由会拒绝合并标签中的受限自定义属性选择器。该路由也不提供 subscriberId 参数；请使用经过策略检查的内联 subscriber，或在示例预览中省略订阅者数据。

要渲染 nodeType 为 action_ab_test 的序列步骤，请将步骤的 sequenceId 和 nodeId 与来自 get_sequence.sequence.emails[].abTest.variants 的 variantId 一起传入。这些步骤本身没有电子邮件，因此必须提供变体；读取和渲染其竞争文案还需要 ab_tests:read 范围。

对于 Supabase，sync_integration 会复用保存在仪表板中的项目、架构、表、列表选择和同意映射。它无法指定任意表。在安装实时数据库触发器后运行它，以导入触发器安装前已存在的用户，然后轮询 get_integration 和 list_integration_activity，查看进度和逐行处理结果。

set_integration_sync_enabled 仅控制批量导入和回填；它不会阻止提供商的实时 webhook 创建联系人。使用 set_integration_list_targeting 选择他们今后的列表成员资格： null 遵循工作区默认设置，[] 表示不加入任何列表，非空数组则指定目标列表。此更改不会追溯生效，也不会移除现有成员资格。它也不会阻止默认的 any_contact 序列，因为这类序列会让未加入列表的联系人加入；明确指定 any_list 和特定列表的序列则要求联系人具有匹配的成员资格。如果还需要停止这些默认加入行为，请同时使用 pause_sequence_enrollments。Supabase、Stripe、Shopify、Wix 和 Webflow 支持此控制。

对于 PostHog，sync_integration 会使用已保存的个人 API 密钥，从头重新启动事件历史导入。导入的事件会去重，因此重试失败的导入不会产生重复项。

对于 Segment，标准 MCP 上的 connect_integration 可在实时 webhook 连接后，选择从 Unify 导入近期事件历史。导入会通过 Profile API 遍历现有联系人，涵盖 API 最近 14 天的数据，跳过没有匹配档案的联系人，并安全处理重试与实时 webhook 的重叠数据。除非明确将 page/screen 名称加入允许列表，否则新连接会跳过自动 page/screen 调用。Segment webhook 密钥必须为 16-153 个 UTF-8 字节。在不提供 connect_integration 的 OpenAI 审核路由上，请改用仪表板或本地 CLI 连接 Segment。使用 sync_integration，通过已保存的凭据重试。

对于 Lemon Squeezy，请传入 provider: "lemon_squeezy"、API 密钥，以及作为 providerAccountId 的数字商店 ID。默认托管设置下，请省略 webhookSecret；响应会报告 webhookProvisioning 和 testMode。仅在手动设置 webhook 时，才提供 16-40 个字符的签名密钥，并使用返回的 webhookUrl。系统绝不会返回凭据。 对于 Attio，标准 MCP 上的 connect_integration 接受工作区访问令牌，无需 webhook 密钥；可选的 settings.listMap 是一个映射，键为 Sequenzy 列表 ID，值为 Attio 人员列表 UUID 或 API slug；还可使用 syncCompanyFromDomain 控制是否根据非免费邮箱域名匹配公司。 在经 OpenAI 审核的接入方式中，请在仪表板或本地 CLI 中连接 Attio，然后使用 update_attio_settings 配置相同的设置。此集成仅支持出站操作： 加入已映射 Sequenzy 列表的新联系人会在 Attio 中创建或更新人员记录，并将其添加到 Attio 列表；从列表中移除联系人不会删除其在 Attio 中的记录。

在编写 {{event.*}} 合并标签或事件属性筛选条件之前，请调用 get_event_schema。省略 eventName 可列出有文档说明的内置事件；提供事件名称可获取特定于提供方的示例负载和属性路径，也可选择通过 provider 筛选。即使结果显示 documented: false，自定义事件名称仍然有效；这仅表示尚未发布参考示例。由于此工具返回的是静态参考数据，请使用集成活动或序列加入记录获取实际发送数据。

对于新的发送域名，请调用 add_sending_domain，发布返回的 website.dnsRecords 中的 DNS 记录，等待 DNS 传播完成，然后调用 verify_sending_domain。请发布所有返回的记录，不要假设提供方或记录数量固定：统一域名包含必需的 DMARC 记录，而旧版域名可能会返回 Amazon SES MAIL FROM 和入站回复记录。如果在创建域名之前尝试验证，错误信息会指向 add_sending_domain，并包含请求的域名。

对于 Shopify，在依赖商品浏览、购物车活动或浏览放弃触发器之前，请调用 get_integration_pixel。由于商家可以单独移除像素，结果会从 Shopify 实时读取。如果 pixel.healthy 为 false，dependentEvents 会列出无法触发的事件；请调用 activate_integration_pixel 安装或重新指向像素。激活操作具有幂等性，事件会从下一次店面访问开始记录，不会回填历史数据。

对于自定义、无头、电商、工单或 SaaS 网站，在依赖商品浏览或购物车触发器之前，请使用 list_web_tracking_keys。创建密钥时请明确指定来源允许列表，安装返回的 installSnippet，然后让客户经过身份验证的后端通过 POST /api/v1/web-tracking-identities 创建短期有效的证明，并在登录或结账时调用 sequenzy.identify(email, identityToken)。仅使用可公开的密钥只能记录匿名活动，无法触发订阅者自动化。返回的代码片段会在异步加载器之前同步安装方法存根，因此在页面引导过程中发出的身份和事件调用会排队等待 SDK 就绪。永久删除密钥之前，建议先使用 update_web_tracking_key 撤销该密钥。

新公司默认没有同步规则。对于 SaaS/电商公司，可通过向 update_sync_rules 传入 null 使用继承的预设；服务和咨询公司通常应保留 []，或定义明确的规则。

使用 list_sender_profiles 查找资料 ID，然后调用 update_sender_profile 仅更改其显示名称。回复地址资料请传入 type: "reply"；默认类型为发件人。地址、发送域名以及帐户级默认发件人/回复地址选择均保持不变。重命名需要 companies:manage 作用域。

使用 delete_sender_profile 永久移除已弃用的发件人身份。该工具不会删除最后一个发件人，也不会删除任何正在使用的资料，包括用于正在运行的营销活动、有效序列（含步骤覆盖）或事务性电子邮件的资料。符合条件的草稿和帐户默认设置会移至返回的 fallbackSenderProfileId；发送前请检查该值。此删除工具不支持回复地址资料。 Shopify 购物车放弃自动化默认启用。购物车闲置一小时后会触发 ecommerce.cart_abandoned，并为每位订阅者设置 24 小时的冷却时间。使用 update_shopify_automation_settings 可更改 cartAbandonment.enabled、delayHours 或 cooldownHours 字段；传入 cartAbandonment: null 可恢复这些默认值，而不更改浏览放弃或降价设置。时间值必须为正数； delayHours 上限为 168，cooldownHours 上限为 720。

订阅者

工具	描述
add_subscriber	添加一位订阅者；状态只能在创建时设置，因此对于现有联系人，请使用 update_subscriber。
create_subscriber_import	将最多 5,000 条完整 CRM 记录加入队列，并可选用可安全重试的 idempotencyKey；启用的电子邮件卫生检查会在摄取完成后继续单独运行。
get_subscriber_import	查看已加入队列的导入任务的进度、各行处理结果数量和失败摘要。
update_subscriber	更新原生个人资料和电话字段、短信同意状态、属性、标签或全局状态。
remove_subscriber	取消订阅并保留抑制历史，或仅在设置 hardDelete: true 时永久删除。
get_subscriber	按电子邮件或外部 ID 获取订阅者详情。
search_subscribers	按查询词、标签、列表、状态、细分或单个自定义属性搜索，并支持自动或可恢复的分页。
trigger_subscriber_event	像集成一样准确发出一条自定义事件，并应用同步规则和匹配的序列触发条件。
trigger_subscriber_events	为一位订阅者按顺序发出多条自定义事件。
import_subscriber_events	跨联系人导入最多 25 条带有来源标识的事件；静默历史记录要求某联系人的每一行都早于一小时。
bulk_add_subscriber_tags	为最多 500 位现有订阅者添加标签；需要 subscribers:tag，也可能需要 tags:write。
bulk_remove_subscriber_tags	为最多 500 位现有订阅者移除标签；需要 subscribers:tag 或 subscribers:write。

对于 CRM 入驻，请使用 create_subscriber_import，不要循环调用 add_subscriber。一次调用可接受 5,000 条完整记录，并返回异步 导入 ID；使用 get_subscriber_import 轮询其状态。导入状态为 completed 时仍可能 包含行级失败，因此请检查 failedCount 和 failedReasons。所有 未处理的行都会计入相应数量：skippedReasons 的总和等于 skippedCount，而 failedReasons 的总和等于 failedCount。如有数量缺失，请连同导入 ID 一起报告， 不要猜测遗漏了哪些行。启用电子邮件卫生检查后， 可送达性检查会在摄取完成后继续单独运行，结果会显示在列表健康状况中；导入状态不会等待这些判定，也不包含这些判定。 无效判定会导致后续发送被抑制。仅当同意状态已核实时，才使用 optInMode: "confirmed"。 对于 import_subscriber_events，如果某一行可能会创建新联系人，则必须提供邮箱；对于现有联系人，externalId 可以单独使用。每一行都要提供稳定的 eventId。重试时会复用原始回执，并以幂等方式重新尝试下游恢复。历史分类按联系人进行：如果某个联系人的任意一行属于近期数据，则该联系人的整组数据都会使用实时副作用路径。

对于合规抑制，请调用 update_subscriber 并设置 status: "unsubscribed"（或调用 remove_subscriber，但不要设置 hardDelete）。不要通过更改状态来重试 add_subscriber：该工具的状态仅在首次创建联系人时生效，而状态不匹配时跳过的结果会被报告为错误。

如果 add_subscriber 未指定 listIds，则通过该调用创建的联系人会加入工作区默认列表，而现有联系人会保留当前的列表归属。若要将现有联系人加入特定列表，请显式传入列表 ID；传入 [] 表示不加入任何列表。

update_subscriber.phone 会写入联系人页面上显示的原生电话号码字段，而非自定义属性。只有在确认获得明确的书面同意后，才传入 smsConsent: true；若要取消联系人的授权，则传入 false。更改电话号码时，如果未传入 smsConsent，系统会重置短信授权，因为授权与原号码绑定。

add_subscriber、update_subscriber 和 create_subscriber_import 接受 IANA timezone，例如 America/New_York。该值会存储在联系人的原生资料中，并启用按收件人当地时间发送营销活动。向 update_subscriber 传入空时区即可清除时区；导入行中无效的时区值会被忽略，不会导致其余导入内容遭到拒绝。

产品与数字内容交付

工具	描述
list_products	列出从 Stripe、Shopify、WooCommerce、手动数据或 Commerce API 数据同步的产品。
upsert_products	创建或更新最多 100 个由你的产品 ID 标识的 Commerce API 产品。
delete_product	删除之前通过 Commerce API 推送的产品。
attach_product_file	将托管文件或本地上传的交付文件附加到产品。
remove_product_file	移除已附加的产品交付文件。
sync_products	将 Stripe 产品目录同步加入队列，还可按 ID 选择集成。

附加产品交付文件后，匹配的购买事件会包含 download.url 和 download.name，因此由购买触发的邮件可以使用 {{event.download.url}} 等合并标签。

对于 Stripe 产品，list_products 会将每个有效价格作为一个变体返回，并将 Stripe 价格 ID 放在 variantId 中。即使某个价格不是产品的默认价格，也可以使用该 ID 在购买序列中指定确切价格。

图片资源

工具	描述
upload_image_asset	上传电子邮件图片，并返回其托管媒体记录及可直接插入的图片块。

该工具接受不超过 5MB 的 PNG、JPEG、GIF 和 WebP 图片。本地 stdio 客户端 可以传入 filePath。能够访问附件字节的托管式／远程客户端可以传入 imageBase64 和 filename。请提供 altText 以满足无障碍访问需求，然后 使用 displayWidthPercent、cropHeight、objectFit（cover 或 contain）和 align，统一截图的呈现方式。返回的 imageBlock 可以 直接复制到营销活动、序列、模板和事务性电子邮件工具接受的区块数组中。

经过身份验证的图片字节始终会上传到由 SEQUENZY_API_URL 配置的源站， 即使反向代理返回了另一主机下等效的上传 URL。API 凭据绝不会转发到该备用源站。

{
  "filePath": "/Users/me/Desktop/product-results.png",
  "altText": "Product results dashboard",
  "displayWidthPercent": 100,
  "cropHeight": 320,
  "objectFit": "cover",
  "align": "center"
}

列表、标签、细分

工具	描述
list_tags	列出所有标签。
create_tag	创建标签定义，可选设置颜色。
update_tag	更新标签颜色。
delete_tag	删除标签并将其从订阅者中移除。
list_lists	列出订阅者列表。
create_list	创建订阅者列表。
update_list	重命名订阅者列表或修改其描述。
delete_list	删除订阅者列表。
add_subscribers_to_list	根据电子邮件数组向列表添加最多 500 名订阅者。
remove_subscribers_from_list	从列表中移除最多 500 名订阅者。
list_segments	列出已保存的细分及其计数。
create_segment	创建嵌套细分或按数组中同一元素筛选的细分。
update_segment	更新细分名称、筛选条件、根组或连接运算符。
delete_segment	删除细分（需要 segments:delete）。
get_segment_count	预览细分中符合条件的活跃订阅者数量。

导出订阅者时，search_subscribers 接受 listId、精确的 listName， 或 list（先按 ID 匹配，再按精确名称匹配）。它还接受 attribute 和 attributeValue，并可通过 attributeOperator 指定 contains、数值比较 或 is_not_empty；仍支持 "attributeName:value" 组合形式。 筛选条件以 AND 组合；如需 OR 逻辑、嵌套组、排除条件、互动情况 或事件条件，请使用已保存的细分。如果省略 limit，该工具会自动 获取所有匹配的分页结果。分块读取时，请传入 limit，并在 hasMore 为 true 时继续使用 pagination.nextCursor（或 pagination.nextOffset）。跳过的 匹配项少于 1,000,000 时支持 offset 和 page；面向更深层的受众时请使用 游标。

批量填充列表时，请使用 add_subscribers_to_list；其底层 API 端点为 POST /api/v1/lists/{listId}/subscribers，末尾不带 /bulk：

{
  "emails": ["[email protected]", "[email protected]"],
  "duplicateStrategy": "skip",
  "enrollInSequences": false,
  "optInMode": "default"
}

每个请求最多发送 500 封邮件。仍需遵守标准 API 速率限制：每个 API 密钥每分钟 100 个请求，突发速率为每秒 20 个请求。对于由 CSV 驱动的 CLI 导入，可接受的邮件表头包括 email、e-mail、email address 和 mail；如果没有可识别的表头，CLI 会读取第一列。

细分筛选器支持属性、事件、已保存的细分成员资格、互动事件、Stripe 产品购买规则和电商产品购买规则。对于匹配任一条件的细分，请使用 filterJoinOperator: "or"；对于嵌套逻辑，请传入 v2 root 组。

对于对象数组属性，请使用通配符路径，例如 history_events[].eventvenue_id:2103。当 AND 组还筛选 history_events[].showing_date 时，两个条件必须匹配同一个 history_events[] 元素；不会合并来自不同历史记录的值。删除细分需要 segments:delete；仅有 segments:write 不够。

每个细分筛选字段都会验证其自身支持的运算符：

• status、segment：is、is_not
• tag：contains、not_contains、is_empty、is_not_empty
• email：contains、not_contains
• emailProvider、list：is、is_not、is_empty、is_not_empty
• firstName、lastName：contains、not_contains、is_empty、is_not_empty
• added：less_than、more_than
• attribute：is、is_not、is_empty、is_not_empty、gte、lte、gt、lt、contains、not_contains
• event、邮件互动字段：is、is_not、at_least、less_than_count
• emailBounced：还支持 is_temporary_bounce、is_permanent_bounce
• stripeProduct：is、is_not、at_least、less_than_count
• stripeCurrentProduct、stripeTrialProduct：is、is_not、gte、lte、gt、lt
• commerceProduct：is、is_not、at_least、less_than_count

Stripe 产品筛选示例：

{ "field": "stripeProduct", "operator": "is", "value": "prod_pro" }
{ "field": "stripeProduct", "operator": "is_not", "value": "prod_pro" }
{ "field": "stripeProduct", "operator": "at_least", "value": "prod_pro:3" }
{ "field": "stripeProduct", "operator": "less_than_count", "value": "prod_pro:3" }

电商产品筛选器用于匹配通过电商订单购买的产品。对于指定提供商的 ID（shopify、woocommerce 或 api），值可以是 provider:productId；也可以使用不带提供商的产品 ID 来匹配任意提供商，或使用 provider:productId:count 来匹配阈值运算符：

{ "field": "commerceProduct", "operator": "is", "value": "api:starter-kit" }
{ "field": "commerceProduct", "operator": "at_least", "value": "shopify:42:2" }

emailSent、emailDelivered、emailOpened、emailClicked、emailBounced 和 emailComplained 等互动字段接受滚动时间范围，例如 7d、30d、90d、180d 或 all。存在性运算符可以通过 marketing:<timeRange>（营销策略下的活动、自动化和 Send API 流量）或 transactional:<timeRange>（事务性策略下的发送）按发送策略限定范围；策略范围需要发送时的策略快照，因此，较早且策略不明确的自动化和 Send API 事件仍只能通过不限定范围的筛选器查询。emailBounced 还支持使用 is_temporary_bounce 和 is_permanent_bounce 限定范围的值。使用 at_least 和 less_than_count 时，请使用 count:timeRange，例如 10:30d 或 10:all。存在性运算符也可以改用活动范围，例如 campaign:cmp_123；活动范围和邮件类型范围不能与计数运算符组合使用。

受众同步（Meta Ads）

工具	描述
list_audience_syncs	列出细分受众群同步任务及其计划和上次同步状态。
list_ad_accounts	列出可用于同步的 Meta 广告账户。
create_audience_sync	按计划将细分受众群推送到 Meta 自定义受众。
update_audience_sync	更改同步频率（hourly、daily、weekly），或暂停／恢复同步。
delete_audience_sync	移除同步映射；Meta 受众本身会保留。
sync_audience_now	在常规计划之外立即触发上传。

需要在 Sequenzy 控制面板中连接 Meta Ads 集成（Settings -> Integrations）。create_audience_sync 接受现有细分受众群（segmentId）或现成模板（predefinedSegmentId，例如 zero-ltv、no-purchase-1y、recent-buyers、high-spenders-ecom、non-buyers、engaged）——首次使用时会自动创建模板细分受众群，并立即执行首次上传。

受众仅支持添加：之后离开细分受众群的订阅者仍会保留在 Meta 受众中。Meta 要求至少匹配 100 人，受众才能用于广告投放。

模板

工具	描述
list_templates	列出模板，并支持按本地化状态、标签和 isTemplate 筛选，以及分页。
get_template	读取模板详情、内容和本地化版本。
create_template	根据提示词、HTML 或 Sequenzy 区块创建模板；使用 isTemplate: true 保存可重复使用的主设计。
update_template	更新模板元数据、收件箱预览文本、标签、HTML 或区块；使用 isTemplate 将主设计标记或取消标记。
set_template_localization	创建或替换由调用方提供的本地化版本。
sync_template_localizations	为选定的或所有已启用的非主要语言区域排队进行 AI 翻译。
delete_template	删除模板。

默认情况下，list_templates 按最新顺序返回 50 封邮件正文，limit 最大可设为 100。当 pagination.hasMore 为 true 时，将 offset 增加 pagination.count； pagination.total 报告所有匹配项的总数，包括营销活动和事务性邮件正文。

在 list_templates 中将 isTemplate 设为 true，只返回已保存的主设计； 设为 false，则返回普通邮件正文。已标记的主设计可用作仪表板序列步骤和营销活动的 起始点；从主设计开始会创建独立副本，因此编辑不会影响主设计。

独立邮件/序列的源设计复制，以及在选定布局中使用 AI 改写，目前仅支持在 仪表板中进行。本次版本有意将这些工作流保留在交互式创作流程中，方便用户在保存序列 步骤前查看源内容、翻译和任何回退文案。REST、CLI 和 MCP 不提供等效的独立邮件/序列源设计 操作。使用 prompt 调用 create_template 会生成新内容，不会保留 现有布局；提供 HTML 或区块会创建新的正文，但不会自动复制本地化版本。请参阅界面可用性文档。

营销活动副本已可通过 REST POST /api/v1/campaigns 和 MCP create_campaign 配合 templateId 使用；它不能与用于 AI 改写的 prompt 同时使用。

对于以自然语言提出的新内容需求，请传入 prompt，让 Sequenzy 在服务器端 生成带品牌风格的原生区块。仅当使用调用方提供的完整 Sequenzy 内容时才使用 blocks， 仅在需要保留提供的标记或明确要求使用标记时才使用 html。prompt、blocks 和 html 互斥；style 和 tone 仅在使用 prompt 时有效。

当译文来自你自己的本地化工作流时，请使用 set_template_localization。它要求提供 已启用的非主要 locale、本地化的 subject，并且 html 和 blocks 必须且只能提供其中之一。使用 sync_template_localizations 可请求 Sequenzy 翻译选定的语言区域； 省略 locales 则同步所有已启用的非主要语言区域。即使禁用了保存时自动本地化，显式同步仍然 有效。

可复用邮件组件

工具	描述
list_email_components	列出已保存的章节和页脚，也可以仅列出已固定的默认组件。
get_email_component	读取单个组件的区块、元数据、版本和默认槽位状态。
get_default_email_component	读取当前固定到默认槽位（例如 footer）的组件。
set_default_email_component	创建或替换新构建的区块邮件使用的公司默认页脚。
create_email_component	根据区块列表保存可复用的章节或页脚。
update_email_component	更新组件元数据，或替换其区块并递增版本号。
delete_email_component	删除组件，但不影响已复制其区块的邮件。

构建邮件时，组件会复制到邮件中，因此后续编辑只会影响新构建的邮件，不会重写现有内容。默认页脚会保留退订链接，而事务性渲染会隐藏该链接。原始 HTML 邮件保留自身标记，不会应用区块组件；发送时的退订处理方式保持不变。

A/B 测试

工具	描述
list_ab_tests	列出 A/B 测试和变体，可选择按序列筛选。
get_ab_test	获取生效设置、变体、本地化状态和序列步骤文案。
get_ab_test_stats	获取汇总统计数据和各变体的统计数据。
restart_ab_test	重启已停止或已完成的 A/B 测试。
select_ab_test_winner	选出营销活动测试的获胜变体，并安排剩余受众的发送。
update_ab_test	更新营销活动或序列的获胜者选择设置。
update_ab_test_variant	更新营销活动草稿或序列变体文案。
create_ab_test	创建营销活动测试，或转换序列邮件步骤。
add_ab_test_variant	向现有 A/B 测试添加变体。
delete_ab_test_variant	删除 A/B 测试草稿变体。
delete_ab_test	删除 A/B 测试。

使用 get_sequence.sequence.emails[].abTest.variants 查找序列变体 ID、主题、预览文本和区块数量；调用 get_ab_test 可审核每个变体的完整 blocks、生效的 settings、本地化状态或统计数据。营销活动设置使用 testPercentage、testDurationMinutes 和 winnerCriteria；序列设置使用 testType、winnerThreshold 和 winnerCriteria。旧版序列值 testPercentage: 100 和 testDurationMinutes: 0 是兼容性哨兵值，并非运行时设置。select_ab_test_winner 仅适用于当前正在测试的营销活动测试，并会立即将获胜变体安排发送给剩余受众。update_ab_test 会更改相应的设置模型；当序列设置会影响正在进行或已使用的测试时，必须传入 confirmLiveChange: true。变体更新只能接受 html 或 blocks，不能同时接受两者。

create_ab_test 必须且只能传入 campaignId 或 automationNodeId 其中之一；后者要求额外提供 1 到 4 个变体，并会将序列邮件节点转换为 action_ab_test。转换会将步骤的主题、预览文本和区块移至独立的变体邮件中。通过 get_sequence 获取测试和变体 ID，使用 get_ab_test 读取每个变体的文案，再通过 update_ab_test_variant 编辑；update_sequence_node 和 update_template 无法编辑变体文案，针对整个步骤的更改必须在每个变体中重复进行。如果 MCP 工具列表中没有 update_ab_test_variant，请在 Sequenzy 连接器上启用该工具，而不要通过其他邮件工具写入。完整工作流需要 ab_tests:read、ab_tests:write 和 sequences:write 权限，这些权限均包含在 更安全的 Agent 访问权限中。只有 sequences:read 权限时，get_sequence 会保留 A/B 步骤和对照文案的可见性，但会隐去测试记录字段，并返回空的变体列表。显式设置的序列 winnerCriteria 会覆盖 testType 默认值，因此内容变体仍可按打开率评判。在活跃序列中转换节点时，请传入 confirmLiveChange: true。A/B 测试（包括对照组 A）最多支持 5 个变体。序列变体会使用独立的邮件模板，可在创建后编辑；序列激活或测试产生互动后，update_ab_test_variant 必须传入 confirmLiveChange: true。只有在测试处于草稿状态时才能添加或移除变体；更改正在运行的序列也需要确认，因为这会立即改变轮换方式。

营销活动

工具	描述
list_campaigns	按状态或标签列出分页结果中的营销活动，其中包含审核者反馈和发送节奏字段，用于账户级别的 STO 审核。
get_campaign	获取营销活动的详情、统计数据、审核者反馈和记录的发送节奏。
get_campaign_audience	解析已保存的定向设置、缺失的引用、通俗易懂的摘要以及实时收件人数。
list_campaign_goals	列出为某个电子邮件营销活动保存的转化目标（不支持 SMS）。
create_campaign_goal	为电子邮件营销活动添加事件、订阅者属性或标签应用类转化目标。
update_campaign_goal	更新已保存的电子邮件营销活动转化目标。
delete_campaign_goal	删除已保存的电子邮件营销活动转化目标。
list_email_sends	搜索近期发送记录，包含资源 ID 和 URL；也可限定为某个序列步骤。成功的实时测试发送不会显示。
get_email_send	根据持久化的电子邮件发送 ID，检查排队中、测试、已发送、已抑制或失败的发送记录。
list_recipient_suppressions	列出关联的受抑制收件人，包括受保护的全局无效地址和投诉。
get_recipient_suppression	检查某个确切收件人的本地退信、投诉、电子邮件卫生状况和区域性 SES 抑制状态。
remove_recipient_suppression	移除工作区软退信升级项，同时保留全局、硬退信和投诉保护。
create_campaign	创建营销活动，设置内容、数据以及可选的发件人/回复地址身份覆盖项。
update_campaign	更新草稿营销活动，包括内容、数据、身份、受众和已保存的 STO 配置。
schedule_campaign	安排或重新安排营销活动，可选覆盖 STO 设置及其 1-24 小时的发送窗口。
send_test_email	向一个地址发送测试电子邮件。
render_email	渲染精确的电子邮件安全 HTML，并报告未解析的标签，包括被默认值掩盖的拼写错误。
cancel_campaign	取消已安排或正在发送的营销活动。
pause_campaign	暂停正在发送的营销活动。
resume_campaign	恢复已暂停的营销活动，可选按时间分散发送。
delete_campaign	删除营销活动。
duplicate_campaign	将营销活动复制为新的草稿。
resend_campaign_to_non_openers	为未打开已发送营销活动的原始受众成员创建重新发送草稿。
通过提示词创建的营销活动会在一次 API 请求中生成并保存，并保持为草稿。只有在复制或保留现有内容，而不是让 Agent 编写内容时，才使用 templateId、blocks 或 html。省略所有内容字段，即可创建一个留待后续编辑的空白草稿。

营销活动目标会将实际收到该营销活动的收件人计入转化，归因窗口采用配置的时长；如果存在打开或点击行为，则仍以该行为作为更强的末次触点信号。事件目标必须提供 triggerEventName，订阅者属性目标必须提供 attributePath，标签应用目标必须提供 triggerTagName。如果省略营销活动归因窗口，其默认值为 168 小时。

如需让每位收件人都在其所在时区的同一墙上时钟时间收到邮件，请调用 schedule_campaign，并设置 sendInRecipientTimezone: true，同时将 scheduledTimezone 设为用于表示 scheduledAt 所对应墙上时钟时间的 IANA 时区。未存储时区的联系人会在 scheduledAt 所指定的时刻收到营销活动。此模式不能与定期发送或分时发送同时使用。

发送时间优化是按营销活动配置的，而不是按公司或序列配置的。可通过 list_campaigns 对所有营销活动进行审查，或使用 get_campaign 检查单个营销活动。在草稿上调用 update_campaign，设置 sendTimeOptimization 和 sendTimeWindowHours（1-24，默认值为 12）；也可以在安排发送时通过 schedule_campaign 覆盖这些设置。spreadOverHours 优先级更高，并会禁用 STO；按收件人时区发送也会禁用 STO。序列使用的则是 sendingWindow，它是一个统一的允许发送时段（小时／日期）限制，而非按收件人预测发送时间。

对于营销活动和序列级别的身份，fromEmail 和 fromName 会选择邮箱中具有该显示名称的发件人身份；如果该身份不存在，则会创建它，而不会重命名其他使用相同地址的身份。Reply-To 地址则在整个公司范围内只有一个已保存名称：当 replyToName 与该名称不同时，会保留已保存名称，并在成功响应的 warnings 中提供恢复指引。

send_email 和 send_test_email 会返回持久化的 emailSendId。可使用 list_email_sends 按主题／标题、收件人、投递状态、类型、退信类型或来源查找最近的 ID；将 ID 传给 get_email_send，即可查看 status、errorMessage、已存储的正文和投递事件。投递列表中的记录会保留 14 天。成功的实时测试邮件和其他测试邮件会被省略，以免淹没真实投递记录。只有启用了入站回复捕获时，这些测试邮件的回复才会显示在 list_conversations 中。队列任务属于内部执行细节，不会通过 MCP 契约公开。每条返回的投递记录都带有直接跳转至控制面板的 url。使用 list_recipient_suppressions 区分受保护的全局无效收件人记录、受保护的公司硬退信记录和投诉记录，与可移除的公司软退信升级记录；使用 get_recipient_suppression 查看准确的区域状态。remove_recipient_suppression 只会移除公司的升级记录；全局和 Amazon SES 账户级抑制、投诉、取消订阅以及邮件清理保护仍然有效。本地清理结果会使用 bounced 原因，并将 email_hygiene 作为来源，而不会更改订阅者的同意状态。

Agent 应在首次尝试前向 send_email 传入由调用方提供的 idempotencyKey，并在对同一封逻辑邮件进行每次重试时重复使用该键。Sequenzy 会在 14 天内返回原始 emailSendId，而不会创建另一条投递记录。如果使用同一键发送不同的参数，请求会被拒绝，因此不要在重试循环中生成新的键。 Email 区块可以使用条件显示规则或 conditional-group 分支。 条件支持渲染时变量和订阅者属性，以及实时订阅者数据，例如细分群组／列表成员资格、标签、事件、互动情况、订阅／SMS 状态，以及 Stripe 或电商购买记录。实时数据条件使用与细分群组筛选器相同的字段值和运算符；没有匹配到已存储订阅者的收件人会使用 OTHERWISE 分支。

核心区块结构包括 { "type": "heading", "content": "Title", "level": 1 }、{ "type": "text", "content": "<p>Copy</p>" }、{ "type": "button", "text": "Book a call", "url": "https://example.com", "variant": "primary" } 和 { "type": "image", "src": "https://...", "alt": "Description", "width": 100, "widthType": "percent" }。按钮也接受 content 作为 text 的别名，默认使用 primary 变体。图片的 widthType 接受 percent 或 px。

YouTube 视频区块接受可选的自定义封面：{ "type": "video", "videoUrl": "https://www.youtube.com/watch?v=...", "thumbnailUrl": "https://cdn.example.com/cover.jpg", "alt": "Watch the product tour" }。 替换区块时，如果未提供 thumbnailUrl，则会恢复为 YouTube 自带的静态画面，同时保留 videoUrl 作为点击目标。

原始 html 会作为一个不透明区块存储。它会保留提供的标记，但不会添加公司徽标、原生品牌区块或由主题驱动的区块设计。新建品牌化草稿请使用 prompt，使用编辑器原生设计请使用 blocks；使用原始 HTML 时，MCP 创作结果会包含一条警告。

使用 update_company 搭配 fromEmail 和／或 replyTo 设置账户级默认值。fromEmail 必须使用已配置并经过验证的发送域名；replyTo 可以是任何有效邮箱。create_campaign、update_campaign、 create_sequence 和 update_sequence 接受相同的直接地址字段，用于资源级覆盖，并会在需要时创建相应的配置文件。 仅发送 fromName 或 replyToName，即可重命名现有默认配置文件，而不更改其地址。当一个地址对应多个显示名称时，请使用 list_sender_profiles 中的 senderProfileId 或 replyProfileId，选择要设为默认并重命名的确切配置文件。

update_company 还可以通过 emailTheme（presetId、colors、typography、layout）管理公司的默认邮件主题。主题更新为部分更新——未提供的字段会保留当前值（或预设默认值），数值会限制在支持的范围内。传入 emailTheme: null 可将公司主题重置为平台默认主题。布局设置可以控制共享的 baseRadius 和独立的 buttonRadius。在 colors 中，background 用于绘制外层画布，content 用于绘制内部内容卡片，surface 用于绘制嵌套卡片或着色区块。省略 content 会保留其当前值；如果未存储内容颜色，卡片会沿用 background。

同一组公司工具还提供回复追踪功能。使用 update_company 搭配 replyTrackingEnabled、replyTrackingDomainMode（sequenzy 或 custom）和 forwardReplies。读取公司信息时也会返回当前只读的 replyRetentionDays 值。

投票和 NPS 调查是原生邮件区块，因此可用于任何接受 blocks 的邮件工具，包括营销活动、模板、A/B 变体、事务性模板和序列邮件步骤。事务性投票发送经过抑制筛选和收件人去重后，必须恰好对应一位有效收件人，且该收件人必须已是订阅者；否则 Sequenzy 会拒绝发送，因为无法安全地将答案链接归属到该订阅者。使用答案按钮式投票：

{
  "type": "poll",
  "variant": "options",
  "question": "What did you think of this email?",
  "options": [
    { "label": "Loved it", "value": "loved" },
    { "label": "Not for me", "value": "not_for_me" }
  ],
  "attributeKey": "email_feedback"
}

对于 NPS，请使用 "variant": "nps"、空的 options 数组，以及 nps_score 之类的属性。量表始终为 0-10；可选的 npsLowLabel 和 npsHighLabel 可自定义两端的说明。每次回答都会更新订阅者属性，并触发 poll.answered，供自动化和出站 Webhook 使用。 在仅含文本的选项投票中设置 "allowMultiple": true，即可打开托管页面， 让收件人选择多个答案并一次性保存整个选择。订阅者属性会存储所选值列表，因此 属性分群应使用 contains。多选投票不能使用选项图片，也不能使用编码后的签名链接 超过安全投递大小限制的配置。营销活动投票摘要会设置 allowMultiple: true，将 受访者数量用作 totalResponses，并且答案百分比总和可能超过 100%。

投票区块还支持针对品牌的样式设置。accentColor 会为所有外观重新着色，包括 "brutal"；optionRadius 以像素为单位设置答案按钮的圆角（0 表示直角），且独立于容器的 styles.borderRadius；questionColor 仅为问题重新着色。 fontFamily 会应用于投票。答案使用 optionFontSize、 optionFontWeight、optionLetterSpacing 和 optionTextTransform 字段，问题则使用对应的 question* 字段。字号和间距的单位为像素，字重范围为 100 到 900，文本转换值为 "none" 或 "uppercase"。

已保存的表单

工具	描述
list_forms	列出已保存的表单及其由服务端管理的受众设置、内容区块和公开操作 URL。
create_form	创建并发布已保存的表单，其中包含标准电子邮件/姓名字段、受众设置、主题和成功行为。
update_form	更新已保存的表单，包括完整且有序的区块数组和类型化自定义字段。
get_form_embed	返回已保存表单的公开操作 URL、托管 JavaScript、精简原生表单和 fetch 示例。

对于 Astro、Hugo、Jekyll、Cloudflare Pages、Netlify、GitHub Pages 或任何其他 静态网站，请调用 list_forms；如果不存在合适的表单，则使用 create_form，然后调用 get_form_embed。返回的不透明 formId 就是公开访问凭证：列表、标签、重复提交行为和成功处理 均保留在服务端，因此部署的浏览器代码中绝不会包含 Sequenzy API 密钥。 对于免费工作区，生成的原生和独立标记中会包含“由 Sequenzy 提供支持”；付费 工作区则会获得无品牌标记。API 会在服务端解析此权益，因此调用方应原样使用返回的代码片段。 更新表单时，未提供的字段保持不变，主题字段则与当前主题合并。传入空的 tagIds 数组可清除标签， 传入空的 redirectUrl 可恢复为确认消息行为。blocks 字段会完整替换现有区块，因此请先用 list_forms 读取当前内容，并保留且仅保留一个必填电子邮件字段和一个提交按钮。将自定义输入项 添加为带有受支持 fieldType 的 form-field 区块；选择、单选和复选字段必须提供选项，而隐藏字段的默认值由服务端强制执行。

已保存的弹出窗口

工具	描述
list_popups	列出已保存的弹出窗口及其状态和互动统计数据，可选择包含完整内容。
get_popup	获取一个弹出窗口的区块、触发条件、定向设置、排期、频率、主题和已发布的嵌入代码。
create_popup	根据起始模板创建弹出窗口，默认设为已发布，并返回其部署脚本。
update_popup	部分更新弹出窗口的文案、受众、行为、主题、区块或发布状态。
get_popup_embed	返回不含密钥的 HTML、React/Next.js、WordPress 和 Shopify 嵌入代码片段。
duplicate_popup	将弹出窗口复制为草稿，其互动计数器独立。
delete_popup	永久删除弹出窗口及其互动计数器。

弹出窗口部署使用一个公开的脚本标签；API 密钥、受众设置、 触发条件、定向设置、排期和频率规则均保留在服务端。 默认情况下，弹出窗口会将联系人添加到每个列表，除非提供了 listIds。更新 区块时，请先读取弹出窗口，再发送完整的替换数组， 并确保其中恰好包含一个必需的电子邮件字段和一个提交按钮。 将 status 设为 draft 会停止弹出窗口，但不会使其现有嵌入代码失效。

落地页

工具	描述
list_landing_pages	列出落地页及其状态、指标、内容和 URL。
get_landing_page	获取落地页详情、构建器内容、指标和已发布的 URL。
render_landing_page	返回有效期为 24 小时的签名访客预览，不会发布页面、计入浏览量或收集注册信息。
create_landing_page	使用默认模板内容或 JSON 创建落地页草稿。
update_landing_page	编辑落地页名称、slug 或完整的编辑器兼容内容。
publish_landing_page	发布落地页，可选择先保存编辑内容。
unpublish_landing_page	将落地页恢复为草稿状态，可选择先保存编辑内容。
duplicate_landing_page	将落地页复制为新草稿，并分配唯一的 slug。
delete_landing_page	删除未发布的落地页。
connect_landing_page_domain	连接自定义落地页域名并返回 DNS 设置详情。
update_landing_page_domain_settings	替换或验证落地页自定义域名设置。

落地页内容使用 Sequenzy 的编辑器兼容 JSON 架构，包含 version、template、seo、theme 和 blocks。SEO 设置包括 faviconUrl 和 hideFromSearchEngines；隐藏的页面会发布 noindex 指令。发布前，请使用 render_landing_page 检查当前访客看到的页面。 其签名 previewUrl 在 24 小时后过期，不公开列出，也不会被编入索引或增加页面浏览量；表单仍会显示，但不会收集联系人信息。区块按插槽顺序渲染： top、hero、form、body，然后是 footer；可将 top 用于显示在主视觉区上方的全宽公告或横幅。 按钮和定价 CTA 的 URL 支持外部 HTTPS 目标或页面内锚点，例如 #form、#section-<sectionId>、#block-<blockId> 和 #top。将 theme.sectionAnimation 设为 none、fade、slide-up 或 zoom-in，并将 theme.sectionAnimationSpeed 设为 slow、normal 或 fast，即可控制已发布页面的滚动显示效果。自定义落地页子域名需要一条指向 pages.sequenzydns.com 的 CNAME 记录；根域名使用指向 76.76.21.21 的 A 记录；如果 www 主机的 CNAME 指向 pages.sequenzydns.com，则会重定向到根域名。DNS 变更生效后，调用 update_landing_page_domain_settings 并设置 verify: true。

序列

工具	描述
list_sequences	按仪表盘状态、搜索、标签、数量上限和偏移量筛选并列出序列。
get_sequence	获取序列详情、A/B 变体 ID 和区块数量（需 ab_tests:read 权限）、节点、边、关联文案以及序列发送时段。
list_sequence_enrollments	分页列出联系人报名记录，并准确归因基于列表、标签、事件或时间的入口。实时序列测试不会创建报名记录。
send_sequence_test_email	向 1-10 位审核者发送一个已保存的 action_email 步骤；A/B 步骤按变体分别检查。
create_sequence	创建空白仪表盘草稿，或创建 AI 生成的／包含明确步骤的序列。
update_sequence	更新标识、设置、报名、现有步骤、分支逻辑，或插入线性步骤。
update_sequence_node	对一个现有序列节点进行类型感知的局部更新。
update_sequence_nodes	以原子方式更新多个现有序列节点。
insert_sequence_step	插入任意类型的仪表盘步骤，包括 AI 生成、出站 Webhook、等待和已连接的分支。
edit_sequence_graph	移动、重新连接、删除或复制图节点；报告已移动或已完成的收件人。
simulate_sequence	试运行当前匹配项、启用就绪状态，以及可选联系人的分支路径，不会报名或发送。
enable_sequence	启用序列。
disable_sequence	冻结序列，阻止新报名并暂停当前收件人。
duplicate_sequence	创建图、邮件和序列 A/B 测试的独立草稿副本。
archive_sequence	将序列移入仪表盘归档，并停止新报名。
unarchive_sequence	将已归档序列恢复为已禁用的草稿。
list_sequence_goals	列出为序列持久化保存的事件、订阅者属性和已应用标签转化目标。
create_sequence_goal	添加事件、订阅者属性或已应用标签转化目标。
update_sequence_goal	更新已持久化保存的序列转化目标。
delete_sequence_goal	删除已持久化保存的序列转化目标。
get_sequence_inbound_webhook	在标准 MCP 上读取入站 URL、设置状态、示例和映射；OpenAI 路由会移除包含凭据的 URL。
configure_sequence_inbound_webhook	配置端点、字段映射和示例；OpenAI 路由会从结果中移除包含凭据的 URL。
rotate_sequence_inbound_webhook_secret	轮换入站序列端点的密钥，并在标准 MCP 上返回替换后的 URL；OpenAI 审核路由不提供此工具。
pause_sequence_enrollments	停止活跃序列的新报名，同时让当前收件人继续进行。
resume_sequence_enrollments	重新开放活跃序列的新报名，不更改当前收件人。
enroll_subscribers_in_sequence	按电子邮件、订阅者 ID 或两者报名最多 500 位订阅者，并支持可安全重试的幂等操作。
cancel_sequence_enrollments	按订阅者或入口事件字段值，停止活跃或等待中的报名。
realign_sequence_enrollments	预览或排队处理，将进行中的等待提前至发送时段开始时间。
get_sequence_enrollment_realignment	轮询已应用的重新对齐任务，并读取已完成的结果或后续游标。
delete_sequence	删除序列。
序列创建支持：

• 仅指定名称创建空白、已禁用的触发器到完成节点的草稿，与控制面板中的草稿一致。
• 控制面板元数据和发送设置：description、labels、userCancellable、序列密送，以及发件人／回复地址身份。
• 使用 trigger: "contact_added"，并指定 listId、多个 listIds 或 listScope： any_contact（默认值）会将所有新增联系人加入序列，包括未加入任何列表的联系人；而 any_list 则会等待联系人实际加入某个列表。
• 使用 trigger: "tag_added"，并指定 tagName 或多个 tagNames；配置的任意标签都会将联系人加入序列。
• 使用 trigger: "segment_entered" 和 segmentId，为已保存细分条件创建进入自动化。
• 使用 trigger: "event_received"，并在主题或正文内容中使用 {{event.*}} 合并标签。
• 使用 trigger: "inbound_webhook"，并指定集成元数据，以创建与控制面板兼容的 Webhook 入口节点。
• 使用 trigger: "inactivity"，并指定 eventName、inactiveDays，以及可选的 inactivityBaseline（sequence_created_at 或 subscriber_created_at）。
• 使用 goal 生成 AI 邮件内容。
• 使用 emailStyle: "visual" 或 "plain" 选择基于目标生成的 AI 邮件的呈现方式；如果省略，则使用公司已保存的偏好设置。
• 使用 Sequenzy blocks 显式指定 steps。
• 显式指定包含 HTML 的 steps，Sequenzy 会将其转换为可编辑区块。
• 显式指定 Update Subscriber 步骤，将触发事件的属性复制到个人资料字段或带类型的自定义属性。
• 使用 delay／delayMs 设置固定等待时间，使用 waitUntil 等待动态日期字段，或使用 waitUntilWeekday 设置日历门控。像 { "day": "sunday", "startTime": "09:00", "endTime": "12:00", "timezone": "America/Los_Angeles" } 这样的星期门控会让流程一直等待，直到下一个符合条件的时间窗口。将其紧接在邮件步骤前，以确保邮件在该窗口内发送；任何介于两者之间的步骤都可能使发送时间移出窗口。队列恢复时，会在释放延迟中的联系人前重新检查该时间窗口。
• 使用动态 Stripe 或 Shopify 折扣操作步骤。每位订阅者到达 create_discount 步骤时，该步骤都会创建一个新的服务商折扣码；后续邮件可使用 {{discount.code}}、{{discount.percentOff}} 和 {{discount.expiresAt}} 等合并标签。
• 对于特定于产品、变体、订单或订阅的事件自动化，使用 enrollmentMode: "matching_field" 和标量 enrollmentFieldPath。带 [] 的数组遍历应放在 propertyFilters 中，而不是加入序列的键中。

对于自定义事件触发器，成功的 create_sequence 结果会包含 eventTrackingCode 和结构化的 eventTracking 对象。该对象包含事件端点、身份与载荷约定、matching_field 加入序列所需的属性路径（如有）、规范化后的触发器 propertyFilters、示例载荷、examplePayloadMatchesFilters、直接事件 API 文档 URL，以及可直接用于 get_integration_guide 的参数。如果匹配状态为 false，请根据 examplePayloadNote 和载荷约定调整示例。启用草稿序列前，请添加此事件流并确认其必需属性。

list_sequence_enrollments 会为每行返回 enteredVia。列表和细分来源会在 value 中保留稳定 ID，并解析出显示用的 name；标签和事件来源会在 value 中保留名称。基于时间的触发器会报告 inactivity 或 frequency，而不会被误认为普通的已接收事件加入记录。实时序列测试不会创建加入记录；它们会发送独立的测试邮件，并将活动记录在序列测试运行中。

对于已确认的手动批量加入操作，请生成一次 idempotencyKey，并且仅在目标顺序和 targetNodeId 完全相同时重复使用该键。回执有效期为 14 天。重试会返回原始的 enrolled、skipped、notFound、targetNodeId 和 scheduledFor 值，并设置 idempotentReplay: true；不会创建令牌，也不会再次将批次加入队列。

动态 Shopify 折扣步骤示例：

{
  "type": "create_discount",
  "discount": {
    "provider": "shopify",
    "discountType": "percent",
    "percentOff": 20,
    "duration": "once",
    "appliesToAllPlans": true,
    "maxRedemptions": 1,
    "codePrefix": "WINBACK"
  }
}

Update Subscriber 步骤示例：

{
  "type": "update_subscriber",
  "nodeType": "action_update_attributes",
  "config": {
    "firstName": "{{event.firstName}}",
    "customAttributeUpdates": [
      { "name": "plan", "value": "{{event.plan}}", "valueType": "text" },
      { "name": "mrr", "value": "{{event.amount}}", "valueType": "number" },
      { "name": "active", "value": "{{event.active}}", "valueType": "boolean" }
    ]
  }
}

数字和布尔值必须是字面量或独立的合并标签。使用 update_sequence.subscriberUpdateSteps，并提供从 get_sequence 获取的 action_update_attributes 节点 ID，以替换现有步骤的配置。

序列更新支持使用 insertSteps 在 get_sequence 返回的 nodeId 之后添加新的线性步骤。仅当要将步骤追加到恰好只有一个线性尾部的序列时，才省略 afterNodeId。insertSteps 支持添加无需配套记录的步骤，例如邮件、延迟、标签／列表操作、属性更新、折扣、条件、等待事件步骤、出站 Webhook 和 AI 步骤。action_ai 步骤需要一个合并标签 prompt、唯一的 resultKey 和一个或多个 outputFields；后续步骤可通过 {{ai.KEY.field}} 读取生成文本或备用文本。所有输出字段的总限制必须符合该步骤 2000 个 token 的响应预算。使用 includeTags、includeEventProperties 或 includeAttributes，选择性地将特定联系人上下文纳入生成；使用 onError（continue、exit 或 fail）选择失败时的行为。多路径 if/else 分支请使用 branch；branch 和 insertSteps 二者只能提供一个。分支条件支持使用 has_tag 和 does_not_have_tag 检查标签是否存在，也支持列表、已保存的细分、事件、点击的链接以及字段比较。每个分支路径都可以提供新 steps、现有 targetNodeId，或两者兼有；备用路径使用 elseSteps 和／或 elseTargetNodeId。目标可以是 get_sequence 返回的完成节点，因此一个原子请求即可将回复路由到完成节点，并将否则路径路由到现有的后续步骤。emails 和 steps 数组可通过 nodeId、emailId 或数组顺序编辑普通的 action_email 步骤。get_sequence.sequence.emails 也包含 action_ab_test 条目；启用 ab_tests:read 后，每个 abTest.variants[] 条目都包含变体 ID、主题、预览文本和区块数量。审核或改写文案前，请调用 get_ab_test 获取完整的变体正文。若按位置更新命中此类条目，更新会被拒绝；必须使用 update_ab_test_variant 按变体更改文案；不要尝试通过 update_template 或 update_sequence_node 重试。使用 insertSteps 创建新步骤；如果插入的邮件需要计时器，请在步骤级别设置 delay、delayMs、waitUntil 或 waitUntilWeekday。waitUntil 接受触发事件中的日期字段，以及可选的 offset、direction（before 或 after）和 missingAction（continue 或 exit）。waitUntilWeekday 接受 day 或 days、startTime、可选的 endTime（默认为 24:00）以及 IANA timezone；已处于时间窗口内的联系人会立即继续。对于正在运行的序列，只有在确认对实时流程的影响后，才可在使用 insertSteps 或 branch 时传入 confirmStructuralChange: true。

insert_sequence_step 可直接创建所有无需配套记录的仪表板步骤：邮件、SMS、延迟、折扣、订阅者更新、标签／列表操作、出站 Webhook、AI 生成、条件、等待和分支。设置 type: "ai"，并提供 prompt、resultKey 和 outputFields，即可为每位联系人生成文本，供后续 {{ai.KEY.field}} 合并标签使用。出站 Webhook 接受 url、method（POST 或 GET）以及值为字符串的 headers。邮件步骤支持事务性模式、按步骤设置身份以及 CC／BCC 投递设置。对于等待门控，请设置 type: "logic_wait_for_event"，并提供 eventName、可选的 timeoutDays（1-365） 以及 timeoutAction（continue 或 exit）。对于分支，请设置 type: "logic_branch"，提供类型化的 branches，并连接其目标：

{
  "sequenceId": "seq_123",
  "type": "logic_branch",
  "afterNodeId": "node_email_1",
  "branches": [
    {
      "id": "replied",
      "conditionType": "event_received",
      "eventName": "email.replied",
      "activityScope": "this_sequence",
      "targetNodeId": "node_complete"
    }
  ],
  "elseTargetNodeId": "node_email_2"
}

通过 get_sequence 返回的每封关联邮件都包含其生效的 emailPreset（branded 或 minimal），与控制面板中的 样式 > 格式相对应。在 emails/steps 项上设置 emailPreset，或在 action_email 节点的 changes 中设置，即可只更改该关联邮件，而不更改公司主题。此操作会对原生 Sequenzy 区块应用与控制面板相同的格式转换，包括包含受支持自定义 HTML 区块的邮件。完全以一个独立原始 HTML 区块存储的邮件，其 emailPreset 会返回 null，且不支持格式更改。由于 html 或 htmlContent 字段会将整封邮件替换为独立原始 HTML，因此不能与 emailPreset 同时使用。

对于序列位置，建议使用关联邮件和邮件节点顶层的 structuralStepNumber。它根据当前图结构计算，与控制面板中显示的步骤徽标一致。并行分支中的邮件有意共用相同的结构深度，而分支长度不同时，合并后的流程会从较长的入向路径继续。关联邮件和节点配置中较旧的 stepNumber 字段会保留原有序号以确保向后兼容，图结构编辑后可能已过时。

每封关联邮件还会返回其已存储的 emailTheme 覆盖项；如果遵循公司主题，则返回 null。在 emails/steps 项上设置 emailTheme，或在 action_email 节点的 changes 中设置，即可仅为该步骤重新设置样式。主题更新采用部分补丁，因此 changes: { "emailTheme": { "colors": { "background": "#f3f4f6", "content": "#ffffff" } } } 会将该邮件的外层画布设为灰色、内容卡片设为白色，同时保留其他颜色、字体排版和布局。省略任一颜色都会保留其当前值。传入 emailTheme: null 可移除覆盖项，重新遵循公司主题。只有在需要更改整个账户的默认设置时，才使用 update_company。

进行单项原位编辑时使用 update_sequence_node；需要以原子方式提交多个节点补丁时，使用 update_sequence_nodes。请先调用 get_sequence：sequence.nodes 中的每一项都包含节点 id、nodeType、当前 config、updatedAt，以及列出可编辑字段和受管理字段并提供准确并发令牌的 updateHints。将该令牌作为 expectedUpdatedAt 传入，以拒绝过时写入。这些工具支持所有已存储的节点类型，包括延迟、电子邮件/SMS 内容、操作、条件、webhook、不更改拓扑结构的分支配置以及触发器。要将 5 分钟的延迟改为 7 天，请为其 logic_delay 节点发送 changes: { "delay": { "days": 7 } }。要将多条创始人风格的备注改为 Minimal，请为相应的 action_email 节点应用补丁：changes: { "emailPreset": "minimal" }。节点类型转换以及边/路径更改应在 edit_sequence_graph 中进行。对于已启用的序列，须在用户确认影响后传入 confirmLiveChange: true；已在等待的收件人会保留原定的计划时间戳。

现有和新插入的电子邮件步骤都可以通过 senderProfileId 或 fromEmail 及可选的 fromName 设置各自的发件人身份，并通过 replyProfileId 或 replyTo 及可选的 replyToName 设置各自的回复地址身份。单独设置 fromName 只会更改该步骤显示的发件人名称。步骤级的 replyToName 同样会覆盖该步骤显示的回复地址名称，而不会重命名公司范围内的回复资料。未明确设置身份字段的新电子邮件步骤会继承最近序列邮件的生效身份。分支合并后，仅继承所有入向路径共有的身份字段；冲突字段则使用序列或公司的默认值。 使用 edit_sequence_graph，并传入 get_sequence 返回的最新 graphRevision，以原子方式重构现有序列。它可以将节点移动到另一节点之前或之后，复用规范化后的 sequence.edges 数组以显式重新连接或调整多个节点的顺序，删除节点，或深度复制节点。复制 A/B 测试会创建独立的测试、变体、邮件和本地化记录，并重置统计数据。将节点移动到分支下方的共享节点之前时，所有汇合的分支路径都会通过该节点重新连接。删除节点后，系统会立即将暂停的收件人移至其唯一的后续节点；若不存在后续节点，则会将其标记为已完成。请检查结果中的 sequence.migratedRecipientCount 和 sequence.completedRecipientCount。如果暂停的收件人会有多个仍然有效的后续节点，则不允许删除。系统也会拒绝过期的版本、无效的分支路径、循环和不可达节点。对于已启用的序列，必须设置 confirmStructuralChange: true。

批量取消前，请先以 dryRun: true 运行 cancel_sequence_enrollments。

更改已启用序列的发送时间窗口后，如果现有与邮件绑定的等待时间需要提前至新窗口的开始时间，请运行 realign_sequence_enrollments。 该工具默认使用 dryRun: true。传入 dryRun: false 会将后台任务加入队列并返回 jobId；请使用 get_sequence_enrollment_realignment 轮询任务。当完成结果中的 hasMore: true 时，请使用其 nextCursor 将下一批有限数量的应用操作加入队列。应用重新对齐会更改实际投递时间，因此只有在用户确认预览后才能使用。

邮件区块

工具	描述
get_email_block_schema	列出所有邮件区块类型，或查看某个类型的必填字段、枚举值、项目结构和示例。

在首次手动编写某种区块类型之前，请先调用 get_email_block_schema。省略 blockType 可列出所有类型；传入 list 或 steps 等类型可查看完整参考；传入 creatableOnly: true 可隐藏由编辑器管理的类型。持久化的 group 区块属于编辑器结构内容：它们会在 Stack、Row、Grid 或单图 Overlay 布局中递归封装子区块，但 AI 生成和 creatableOnly 会有意将其省略。读取或更新现有分组内容时，请传入 blockType: "group" 以查看其字段。列表使用独立的区块类型，而非 text 变体：list 项使用 content，而 steps 项使用 title 和可选的 description。

接受 blocks 的工具会将每个区块的视觉样式保存在其 styles 对象中：

{
  "type": "card",
  "title": "Your update",
  "content": "Everything is ready.",
  "variant": "default",
  "styles": {
    "backgroundColor": "#f8fafc",
    "backgroundOpacity": 85,
    "borderColor": "#cbd5e1",
    "borderWidth": 1,
    "borderRadius": 12
  }
}

为兼容较早的 Agent 提示词，也接受 backgroundColor、backgroundOpacity、borderColor、borderWidth 和 borderRadius 等顶层样式键，并会将其保存在 styles 下。

事务性邮件

工具	说明
list_transactional_emails	搜索／筛选模板并按投递指标排序；返回主题和控制面板 URL。
get_transactional_email	按 ID 或 slug 查看事务性邮件。
create_transactional_email	根据提示词、HTML 或区块创建事务性模板。
update_transactional_email	更新事务性邮件的元数据或正文内容。
send_email	通过模板或 HTML 向共享的 To、Cc 和 Bcc 收件人发送一封邮件。

通过提示词创建的事务性模板由服务端生成，默认处于禁用状态，以便审核。 显式指定 HTML 或区块的模板则默认启用，以保持兼容性；可显式传入 enabled 覆盖任一默认值。

直接发送时，传入 to、subject 和 html；MCP 服务会将 html 映射到事务性 API 的 body 字段。发送已保存的事务性邮件时，则通过兼容性命名的 templateId 字段传入其 API slug。 对于事务性邮件发送，to、cc 和 bcc 各自接受一个地址或最多 50 个地址组成的数组。API 会向共享收件人列表发送一封邮件，并按 to、cc、 bcc 的优先顺序移除不同字段之间的重复地址。 营销邮件发送仍要求 to 中恰好有一个有效地址，且不支持其他收件人。 send_email 的变量支持用于重复区块的嵌套数组，例如 { "event": { "items": [...] } }。当收件人通过外部 ID 或电子邮件地址匹配到已存储的 订阅者时，系统会自动使用已保存的名和姓填充未提供的姓名变量。 显式值（包括空白值）优先。 可选的 attachments 数组最多接受 10 个文件／总计 7MB。每个项目都需要包含 filename，且必须且只能包含 Base64 content 或公开的 HTTP(S) path 之一。 设置 contentId 可嵌入 HTML 引用的 CID 图片，还可选择设置 contentType 来覆盖 MIME 类型检测。 省略 trackingSettings 时，将使用公司事务性 API 的默认跟踪设置。可使用 trackingSettings.clickTracking: false 或 trackingSettings.openTracking: false，为单次发送禁用链接重写或开启 像素。这些单次发送选项只能选择退出，不能启用账号级或事务性 API 默认设置已禁用的跟踪。使用 get_tracking_settings 和 update_tracking_settings 可查看或更改这些默认值。

对于 Agent 和工作流重试，请在 send_email 中包含稳定的 idempotencyKey（最多 255 个字符）。每封逻辑邮件使用一个键，重试时发送相同参数；该键有效期为 14 天。

分析

工具	描述
get_stats	获取 7d、30d 或 90d 的概览统计数据；可按结构化邮件类型筛选。
get_transactional_stats	按 ID 或 slug 获取一封已保存事务性邮件的全时段或指定时间范围指标。
get_campaign_stats	获取营销活动表现、回复指标、关联的转化目标以及 Poll/NPS 摘要。
list_poll_responses	列出每位受访者在各区块中的最新 Poll/NPS 答案，以及身份信息和回复时间。
get_sequence_stats	获取序列的汇总表现和各步骤表现，以及按当前节点分组的实时活跃和等待中注册数量。
list_email_metrics	对比营销活动和序列步骤的漏斗、回复、转化与收入，包括跨序列步骤。
list_campaign_events	分页列出营销活动的原始邮件事件。
list_sequence_events	分页列出序列的原始事件，可选择限定到某个邮件步骤。
get_subscriber_activity	获取订阅者的邮件统计数据、活动记录和注册信息。

营销活动和序列事件筛选器接受 transport_failure，以及投递、退信、投诉、互动、退订和延迟事件。 传输失败表示 MTA 基础设施或出口路径资源耗尽；这不会将有效的收件人地址归类为退信。

分析工具默认排除检测到的机器人、扫描器、链接预览和受跟踪资源的打开/点击事件。需要原始互动诊断数据时，可向 get_stats、get_campaign_stats、get_sequence_stats、get_ab_test_stats、get_subscriber 或 get_subscriber_activity 传入 includeMachineEngagement: true；在 API 返回事件级活动数据时，包含的打开/点击活动行会显示 machine、engagementQuality 和 classificationReasons 字段。

get_sequence_stats.enrollmentCounts 是按当前节点分组的活跃和等待中注册运行的实时快照。它统计注册令牌，不一定是不同的订阅者数量，且不受历史 period、start 或 end 筛选条件限制。

使用 list_email_metrics 可对比不同营销活动或序列步骤。传入 step 和可选的 sequenceId 值，可汇总多个序列中的同一步骤；使用返回的 automationNodeId 调用 list_sequence_events 或 list_email_sends 检查收件人。campaignId 不能与 sequenceId 或 step 同时使用。明确指定营销活动和序列范围后，即使配置的邮件没有活动记录，也会保留在结果中，避免表现不佳的邮件被悄然省略。

向 get_stats 传入 emailType: "transactional"，可获取 Send API 和事务性 SMTP 投递、打开、点击及回复率。这包括直接发送和已保存模板发送。需要查看某次投递的状态和事件时间线时，可将 send_email 返回的 emailSendId 用于 get_email_send。需要获取一封已保存事务性邮件的汇总比率时，可使用 get_transactional_stats。其响应包括最常点击的链接、投诉、回复、最新的永久/临时退信分类，以及单独的人类和机器打开/点击数量。直接内容发送没有稳定的模板 ID，但仍可通过账户事务性统计数据和投递搜索查询。 当营销活动收集投票或 NPS 答案时，get_campaign_stats 会包含一个顶层 polls 数组。每位订阅者在每个投票区块中只计一次，使用其最新答案。NPS 汇总包括分数、平均值，以及推荐者、中立者和贬损者的数量。即使互动指标使用了时间筛选，这些响应汇总仍统计全部历史数据。

使用 list_poll_responses 查看谁在何时回答了什么。它会按时间倒序返回每位订阅者在每个投票区块中的最新答案，包括邮箱、存储值、属性键和响应时间。传入 blockId 可限定单个投票；对于序列邮件步骤，请将其自动化节点 ID 作为 campaignId 传入。请勿通过扫描订阅者属性来重建此历史记录：属性没有响应时间戳，而且后续邮件可能复用了同一个键，从而覆盖原值。

要列出某个计数背后确切的历史响应者，请使用字段 pollResponse、运算符 is，以及限定营销活动和汇总中 blockId 的 JSON 值调用 create_segment：

{
  "v": 1,
  "campaignId": "camp_123",
  "blockId": "poll_1",
  "match": { "kind": "answer", "value": "loved" }
}

对于 NPS，使用类似 {"kind":"npsBucket","bucket":"detractors"} 的匹配条件；有效的类别为 promoters、passives 和 detractors。汇总中的 attributeKey 存储的是订阅者当前／最新的响应；后续投票若复用了该键，可能会覆盖此值，因此它不能用于精确查询历史数据。

团队、收件箱、Webhooks

工具	描述
list_team_members	列出团队成员和待处理的邀请。
invite_team_member	邀请队友担任管理员或查看者，并可选择授予账单访问权限。
cancel_team_invitation	取消待处理的团队邀请。
list_conversations	按状态和未读筛选条件列出订阅者回复会话。
get_conversation	查看会话及其消息历史记录。
reply_to_conversation	将回复加入发送队列，或添加内部备注。
update_conversation_status	打开或关闭会话。
mark_conversation_read	将会话中的所有消息标记为已读。
list_webhooks	列出出站 Webhook 端点。
create_webhook	创建端点，并在标准 MCP 中返回一次性签名密钥；OpenAI 审核的路由不提供此工具。
update_webhook	更新 Webhook 名称、URL、事件或状态。
delete_webhook	永久删除 Webhook 端点及其投递历史记录。
test_webhook	向 Webhook 端点发送测试事件。
list_webhook_deliveries	列出 Webhook 最近的投递尝试。
replay_webhook_delivery	重放一次 Webhook 投递。

每个列表的同意状态变更可作为选择启用的出站事件提供： subscriber.list_subscribed 和 subscriber.list_unsubscribed。其负载会标识订阅者和列表，将 action 报告为 added 或 removed，并包含变更的 source（例如 preferences_page、dashboard、api 或 automation）。

对于 MTA 传输路径耗尽等最终投递失败，请使用 email.failed 事件。收件人退信仍使用 email.bounced。

当工作流需要在电子邮件或 SMS 活动完成后收到一次最终通知时（包括有效的零收件人发送），请使用仅可显式启用的 campaign.sent 事件。在标准 MCP 中，如果 create_webhook 未提供 events，则不会添加此事件；在 OpenAI 审核的路由中，创建或编辑 Webhook 时请在控制面板中添加该事件。

AI 生成

工具	说明
generate_email	根据提示词生成带品牌元素的邮件内容块。
generate_sequence	已弃用的别名，用于保存基于目标的序列草稿。
generate_subject_lines	生成 A/B 测试主题行变体。

生成的邮件内容默认包含公司的徽标和页脚。 generate_email 支持使用 applyBranding: false 生成原始内容块，并可使用 emailType: "transactional" 生成不含取消订阅链接的页脚。 基于提示词的营销活动会沿用公司配置的邮件字体。生成的内容会以草稿形式返回，供审核。使用 create_sequence 可生成并保存处于禁用状态的序列草稿，该草稿会显示在 list_sequences 中；已弃用的别名 generate_sequence 也会执行相同操作。

SMS

工具	说明
generate_sms	根据提示词生成 SMS 文案。
get_sms_settings	查看 SMS 插件的就绪状态、额度、默认设置和已配置的号码。
get_sms_usage	按号码比较发送量、投递结果、扣除的额度、最近活动和测试发送量。
update_sms_number_label	更新号码标签或该号码的品牌前缀覆盖设置。
release_sms_number	将号码永久退还给运营商，并释放其工作区名额。
send_test_sms	发送测试消息，可通过 fromNumberId 选择已配置的发送号码。

release_sms_number 不可撤销。绑定到已释放号码的营销活动或序列步骤会跳过 SMS 发送，直到将其重新指定到一个有效号码。get_sms_usage 会将生产环境的总量与 testSends 分开报告。 如果 send_test_sms 未指定 fromNumberId，则会像生产环境发送一样，默认使用最早激活的号码。测试发送会发送真实消息并扣除额度，会绕过静默时段限制，且每家公司在滚动 24 小时内最多发送 100 条。

产品反馈

仅当用户明确要求助手向 Sequenzy 团队发送反馈时，才使用 submit_feedback。 如有需要，Standard MCP 可为该报告附带结构化复现字段 userIntent、toolCalls、expected、actual 和 resourceIds。OpenAI 审核的路由仅接受消息、类别以及可选的概括性工作流上下文。请勿包含无关的订阅者数据、邮件内容、原始 API 负载、调试数据或机密信息。

资源

服务器还会公开只读的 MCP 资源。

资源	说明
sequenzy://dashboard	最近 7 天的实时概览统计数据。
sequenzy://company	当前公司和本地化设置。
sequenzy://campaigns/recent	最近 10 个营销活动及其状态和基本统计数据。
sequenzy://subscribers/recent	最近添加的订阅者。
sequenzy://subscribers/engaged	最活跃或参与度最高的订阅者。
sequenzy://sequences	所有序列及其状态。
sequenzy://templates	模板及其本地化状态。
sequenzy://segments	已保存的细分及订阅者数量。
sequenzy://tags	标签及其使用次数。
sequenzy://health	投递能力指标和健康状态。
sequenzy://email-blocks	每种邮件区块类型的字段参考。
sequenzy://app-routes	仪表盘路由模板和设置选项卡。

示例提示词

Add [email protected] with tags "vip" and "developer", then put them on the beta list.

Create a 4-email churn prevention sequence for users whose subscription expires soon. Leave it in draft mode.

Create a segment for subscribers who bought Stripe product prod_pro at least 3 times.

Draft a campaign about our new analytics dashboard, target the Pro users segment, and send a test to me.

How did the last campaign perform compared with the one before it?

安全

• 使用个人 API 密钥，而非共享的团队密钥。
• 密钥只能访问你的 Sequenzy 用户有权访问的公司。
• 不再需要访问权限时，请前往 Settings -> API Keys 撤销密钥。
• 保持启用客户端审批提示，以确认发送、安排、删除和批量更改操作。
• 营销活动和序列优先采用草稿工作流，然后在 Sequenzy 中审核后再启动。

故障排除

SEQUENZY_API_KEY environment variable is required

在 MCP 客户端配置中设置 SEQUENZY_API_KEY，或运行：

npx @sequenzy/setup

API 密钥无效

在 Settings -> API Keys 中创建新的个人密钥，更新 MCP 配置，然后重启客户端。

API 密钥缺少权限范围

调用 get_account 并检查 apiKeyPermissions。本地连接应 打开 apiKeyPermissions.manageUrl，为已加载的密钥添加缺失的权限范围，然后 重试，无需重启。只有已拥有 api_keys:manage 权限的公司密钥才能通过 update_api_key 更新；请在账户级别的 API Keys 页面编辑个人密钥。托管式 OAuth 连接也可以断开连接，然后 使用更广泛的权限重新授权。工具错误会包含所需的具体权限范围。

资源重复

如果工具调用将创建重名的细分或发送域名，服务器会返回稳定的 code、便于 Agent 理解的 description、具体的 resolution 以及 docsUrl。对于细分，请调用 list_segments 并复用现有细分 ID，或选择其他名称。对于网站，请调用 list_websites；如果所选公司的网站列表中没有该域名，则该域名属于其他公司或账户，必须将其删除、重新分配，或替换为其他发送域名。

工具未显示

• 确认客户端所使用的环境中有 npx。
• 编辑配置后重启 MCP 客户端。
• 检查配置是否位于对应客户端的正确位置。

网络或 API URL 问题

服务器默认使用 https://api.sequenzy.com。如果你覆盖了此设置，请确认 SEQUENZY_API_URL 指向可访问的 Sequenzy API 基础 URL。

开发

bun install
bun test
bun run type-check
bun run build

MCP 工具架构必须与严格的客户端保持兼容：

• 工具 inputSchema 根节点必须是普通的 type: "object" 架构。
• 不要在工具架构的任何位置发布 anyOf。
• 不要在工具架构的根节点放置 oneOf、allOf、enum 或 not。
• 在处理程序中强制执行条件要求，并通过测试验证。

此独立仓库镜像了 Sequenzy 主单体仓库中维护的 MCP 软件包。同步规则请参阅 AGENTS.md。

许可证

MIT

面向 Agent 的发现

Sequenzy 为 Agent 网络和 A2A 式发现发布机器可读的清单：

• 远程 MCP 端点：https://api.sequenzy.com/v1/mcp
• Agent 能力清单：agent-capability.json
• A2A 式 Agent 卡片：.well-known/agent-card.json
• OpenClaw/Moltbot 技能元数据：openclaw/skill.json
• OpenClaw/Moltbot 操作指南：openclaw/SKILL.md

这些文件将 Sequenzy 描述为一项供 Agent 使用的授权邮件自动化能力，并明确排除抓取、垃圾邮件和未经请求的冷邮件推广用途。

工作区角色

账户密钥访问权限由密钥范围和你当前的工作区角色共同决定。get_account 会在 apiKeyPermissions.roleRestrictedScopes 中报告受限范围；canSendLive 表示至少有一种获准的发送工作流可用，并不代表所有发送工具都获准使用。

你可以邀请 marketer 来管理订阅者、营销活动和序列，而不授予其访问事务性邮件、工作区设置、团队或账单的权限。营销人员可以选择现有的发件人／回复档案。由事务性邮件支持的营销活动、A/B 测试和序列来源，在预览、共享、分析和发送历史记录中仍受保护。营销人员和受限成员无法获得账单访问权限。