Composio Mailchimp 工具接入与故障排查指南server prefix、connectionConfig 与 Proxy Execute 全解析【免费下载链接】composioComposio powers 1000 toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.项目地址: https://gitcode.com/GitHub_Trending/co/composioMailchimp 是 Composio 中一个成熟的 email newsletters 类工具包toolkit提供 275 个工具与 4 个触发器涵盖营销活动、受众管理、自动化流程与数据分析等能力。本文以仓库中 docs/content/toolkits/faq/mailchimp.md 的官方 FAQ 为骨架结合 docs/content/kb/guide/toolkits-mailchimp.mdx 知识库文档与 TypeScript/Python SDK 源码系统梳理 Mailchimp 连接配置中最高频的五个问题——server prefix 取值、connectionConfig 字段命名、套餐限制、Proxy Execute 原始令牌调用与触发器支持——并提供可直接照做的解决方案。读完本文你将能独立定位并解决「连接看起来正常但工具调用失败」的 Mailchimp 类问题也能正确使用subdomain/dc字段完成 OAuth 连接与原始 access token 的代理执行。Mailchimp 工具包在 Composio 中的定位在深入故障排查之前先明确 Mailchimp 工具包的基本事实数据来源 docs/public/data/toolkits.jsonslugmailchimp认证方案仅支持OAUTH2Composio 托管认证同样为OAUTH2工具规模275 个工具、4 个触发器类别email newsletters邮件营销与自动化版本当前仓库数据版本为20260821_00从 TS CLI 侧的工具包 slug 生成列表ts/packages/cli/src/generated/toolkit-slugs.ts中同样可以看到mailchimp已注册说明该工具包在 CLI 与 API 两端均可直接引用。Mailchimp 工具能力覆盖营销全链路例如MAILCHIMP_ADD_CAMPAIGN创建营销活动、MAILCHIMP_ADD_LIST创建受众/列表、MAILCHIMP_ADD_AUTOMATION创建经典弃购自动化、MAILCHIMP_ADD_EVENT为列表成员添加事件可用于细分与触发自动化等。注意MAILCHIMP_ADD_AUTOMATION的描述明确指出经典自动化仅对已创建过经典自动化的付费 Mailchimp 账户开放——这正是下文套餐问题的实践体现之一。问题一server prefix 必须取.admin.mailchimp.com之前的部分症状Mailchimp 连接显示正常但 API 调用失败即使 API key/token 本身看起来正确。根因Mailchimp 是数据中心datacenter分布式的服务每个账户绑定一个服务器前缀server prefix形如us19、us20、us21。该前缀是构建所有 API 请求 URL 的基础传入错误前缀会导致请求打到错误的数据中心从而失败。解法server prefix 就是 Mailchimp 管理后台 URL 中.admin.mailchimp.com之前的字段。例如后台地址https://us19.admin.mailchimp.com/→ server prefix us19后台地址https://us20.admin.mailchimp.com/→ server prefix us20官方 FAQ 原文docs/content/toolkits/faq/mailchimp.md强调前缀错误会导致 Mailchimp API 调用失败即使 API key/token 本身看起来正确。因此排查顺序应当是先验证前缀再怀疑凭证。问题二connectionConfig 必须传subdomain或兼容别名dc而不是server_prefix症状按照 UI 上的「Server Prefix」标签填写了配置但工具调用依旧失败。根因Composio 的 connected account 校验器validator中Mailchimp 的配置字段名是subdomain兼容旧的dc别名server_prefix这个键会被校验器忽略并可能回退到默认值如us21。也就是说UI 文案与 API 字段名不一致这是最典型的踩坑点。解法在创建连接时将 server prefix 值放到connectionConfig.subdomain字段或用旧别名connectionConfig.dc不要发送server_prefix。这一点在仓库源码中得到直接印证。核心类型定义 ts/packages/core/src/types/connectedAccountAuthStates.types.ts 中的BaseSchemeRaw是一个 Zod schema它显式声明了// for posthog, freshdesk, zendesk, clickup and others subdomain: z.string().optional(), // for mailchimp dc: z.string().optional(),源码注释明确标注subdomain服务于多个需要子域的工具包而dc是 Mailchimp 专属的兼容字段。因此传参时二选一即可推荐使用subdomain。以 SDK 创建连接为例示意await composio.connectedAccounts.create({ integration: mailchimp, authScheme: OAUTH2, connectionConfig: { subdomain: us19, // 不要写 server_prefix }, });问题三部分 Mailchimp 工具要求至少 Essentials 套餐症状连接与配置全部正确但某些工具如自动化、高级细分仍然报错。根因Mailchimp 的 API 能力随套餐分级。免费账户Free plan可用的 API 能力有限部分工具/API 能力要求账户至少为Essentials套餐付费入门级。FAQ 原文docs/content/toolkits/faq/mailchimp.md明确指出免费 Mailchimp 账户可能不足以支撑请求的工具流程。解法先确认连接配置与 server prefix 无误见问题一、二再核对目标工具在 docs/public/data/toolkits.json 中的描述看是否有套餐前置条件若确为套餐限制需用户在 Mailchimp 侧升级到 Essentials 及以上套餐。仓库工具描述中有多处套餐相关细节佐证例如MAILCHIMP_ADD_LISTAdd list注明免费 Mailchimp 账户仅限 1 个受众audience付费套餐支持多个受众MAILCHIMP_ADD_AUTOMATION注明经典自动化仅对已创建过经典自动化的付费账户开放。这些都属于「连接正确但工具因账户权限失败」的典型场景。问题四Proxy Execute 使用原始 access token 时必须同时携带 subdomain场景通过 Composio 的 Proxy Execute 能力用 Mailchimp 自定义连接数据custom connection data直接执行工具而不走 Composio 托管 OAuth 流程。要求调用/api/v3/tools/execute/proxy时val中必须同时包含access_tokenMailchimp OAuth 原始访问令牌subdomainserver prefix如us20同时请求体需要携带toolkitSlug: mailchimpauthScheme: OAUTH2FAQ 原文给出的完整参数组合如下docs/content/toolkits/faq/mailchimp.mdPOST /api/v3/tools/execute/proxy { toolkitSlug: mailchimp, authScheme: OAUTH2, val: { access_token: oauth-access-token, subdomain: us20 } }漏传subdomain是 Proxy Execute 模式下最容易被忽略的错误凭证正确但请求仍打到默认数据中心导致执行失败。需要特别说明Proxy Execute 面向「自定义连接数据」的高级用法常规场景仍建议走标准 OAuth 连接流程由 Composio 管理令牌与数据中心的绑定。问题五Mailchimp 支持触发器但使用前需核对具体事件Mailchimp 出现在 Composio 的 supported-trigger 工具包列表中当前仓库数据docs/public/data/toolkits.json显示其triggerCount为 4。实践建议FAQ 原文 docs/content/toolkits/faq/mailchimp.md使用某个具体 Mailchimp 触发器前先核对确切的触发器/事件在当前工具包版本中是否存在可在 docs/public/data/toolkits.json 的triggerCount与工具列表、或 Composio 平台工具包页面上确认若所需事件不存在通过 Composio 的请求入口request portal提交用例由平台评估并排期新增。这一策略同样适用于其他工具包的触发器接入工具包名出现在支持列表 ≠ 任意事件都可用事件粒度需要以当前版本为准。进阶Mailchimp 输出已升级为强类型响应除了上述五个 FAQ 场景仓库 changelogdocs/content/changelog/02-03-26.mdx记录了一个与 Mailchimp 工具使用强相关的演进Mailchimp 与 GitHub、Trello 一起成为首批获得强类型响应typed responses的工具包之一。该变更意味着所有 Mailchimp 工具输出返回强类型对象字段有清晰文档而非泛化的response_datablob获得更好的 IDE 自动补全与字段校验Agent 解析输出时更可靠破坏性变更提醒如果你使用latest版本且代码依赖旧的response_data结构需要更新代码适配新的类型化响应 schema。对 Agent 开发者而言这意味着接入 Mailchimp 工具后可以直接按类型化字段读取返回结果如 campaign id、list id 等减少手工解析错误。排查清单速查将上述问题整理为一份可执行的排查顺序步骤检查项正确做法错误做法1server prefix 取值取.admin.mailchimp.com之前部分如us19整段 URL 或留空2connectionConfig 字段名subdomain或旧别名dcserver_prefix被忽略回退us213Mailchimp 套餐确认目标工具是否要求 Essentials 及以上免费账户跑高级工具流程4Proxy Execute 载荷val中同时给access_tokensubdomain只给 access_token5触发器事件核对具体事件在当前版本存在仅凭工具包名在支持列表就假设全部可用总结Mailchimp 工具包接入失败的高频原因可以收敛为「三个字段、一个套餐、一个校验」subdomain字段名而非server_prefix、正确的 server prefix 值.admin.mailchimp.com之前部分、Proxy Execute 时补全subdomain以及免费/付费套餐对 API 能力的限制。这些结论均以仓库官方 FAQdocs/content/toolkits/faq/mailchimp.md、知识库文档docs/content/kb/guide/toolkits-mailchimp.mdx和源码 schemats/packages/core/src/types/connectedAccountAuthStates.types.ts为依据可在接入与排障时直接对照使用。【免费下载链接】composioComposio powers 1000 toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.项目地址: https://gitcode.com/GitHub_Trending/co/composio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Composio Mailchimp 工具接入与故障排查指南：server prefix、connectionConfig 与 Proxy Execute 全解析
Composio Mailchimp 工具接入与故障排查指南server prefix、connectionConfig 与 Proxy Execute 全解析【免费下载链接】composioComposio powers 1000 toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.项目地址: https://gitcode.com/GitHub_Trending/co/composioMailchimp 是 Composio 中一个成熟的 email newsletters 类工具包toolkit提供 275 个工具与 4 个触发器涵盖营销活动、受众管理、自动化流程与数据分析等能力。本文以仓库中 docs/content/toolkits/faq/mailchimp.md 的官方 FAQ 为骨架结合 docs/content/kb/guide/toolkits-mailchimp.mdx 知识库文档与 TypeScript/Python SDK 源码系统梳理 Mailchimp 连接配置中最高频的五个问题——server prefix 取值、connectionConfig 字段命名、套餐限制、Proxy Execute 原始令牌调用与触发器支持——并提供可直接照做的解决方案。读完本文你将能独立定位并解决「连接看起来正常但工具调用失败」的 Mailchimp 类问题也能正确使用subdomain/dc字段完成 OAuth 连接与原始 access token 的代理执行。Mailchimp 工具包在 Composio 中的定位在深入故障排查之前先明确 Mailchimp 工具包的基本事实数据来源 docs/public/data/toolkits.jsonslugmailchimp认证方案仅支持OAUTH2Composio 托管认证同样为OAUTH2工具规模275 个工具、4 个触发器类别email newsletters邮件营销与自动化版本当前仓库数据版本为20260821_00从 TS CLI 侧的工具包 slug 生成列表ts/packages/cli/src/generated/toolkit-slugs.ts中同样可以看到mailchimp已注册说明该工具包在 CLI 与 API 两端均可直接引用。Mailchimp 工具能力覆盖营销全链路例如MAILCHIMP_ADD_CAMPAIGN创建营销活动、MAILCHIMP_ADD_LIST创建受众/列表、MAILCHIMP_ADD_AUTOMATION创建经典弃购自动化、MAILCHIMP_ADD_EVENT为列表成员添加事件可用于细分与触发自动化等。注意MAILCHIMP_ADD_AUTOMATION的描述明确指出经典自动化仅对已创建过经典自动化的付费 Mailchimp 账户开放——这正是下文套餐问题的实践体现之一。问题一server prefix 必须取.admin.mailchimp.com之前的部分症状Mailchimp 连接显示正常但 API 调用失败即使 API key/token 本身看起来正确。根因Mailchimp 是数据中心datacenter分布式的服务每个账户绑定一个服务器前缀server prefix形如us19、us20、us21。该前缀是构建所有 API 请求 URL 的基础传入错误前缀会导致请求打到错误的数据中心从而失败。解法server prefix 就是 Mailchimp 管理后台 URL 中.admin.mailchimp.com之前的字段。例如后台地址https://us19.admin.mailchimp.com/→ server prefix us19后台地址https://us20.admin.mailchimp.com/→ server prefix us20官方 FAQ 原文docs/content/toolkits/faq/mailchimp.md强调前缀错误会导致 Mailchimp API 调用失败即使 API key/token 本身看起来正确。因此排查顺序应当是先验证前缀再怀疑凭证。问题二connectionConfig 必须传subdomain或兼容别名dc而不是server_prefix症状按照 UI 上的「Server Prefix」标签填写了配置但工具调用依旧失败。根因Composio 的 connected account 校验器validator中Mailchimp 的配置字段名是subdomain兼容旧的dc别名server_prefix这个键会被校验器忽略并可能回退到默认值如us21。也就是说UI 文案与 API 字段名不一致这是最典型的踩坑点。解法在创建连接时将 server prefix 值放到connectionConfig.subdomain字段或用旧别名connectionConfig.dc不要发送server_prefix。这一点在仓库源码中得到直接印证。核心类型定义 ts/packages/core/src/types/connectedAccountAuthStates.types.ts 中的BaseSchemeRaw是一个 Zod schema它显式声明了// for posthog, freshdesk, zendesk, clickup and others subdomain: z.string().optional(), // for mailchimp dc: z.string().optional(),源码注释明确标注subdomain服务于多个需要子域的工具包而dc是 Mailchimp 专属的兼容字段。因此传参时二选一即可推荐使用subdomain。以 SDK 创建连接为例示意await composio.connectedAccounts.create({ integration: mailchimp, authScheme: OAUTH2, connectionConfig: { subdomain: us19, // 不要写 server_prefix }, });问题三部分 Mailchimp 工具要求至少 Essentials 套餐症状连接与配置全部正确但某些工具如自动化、高级细分仍然报错。根因Mailchimp 的 API 能力随套餐分级。免费账户Free plan可用的 API 能力有限部分工具/API 能力要求账户至少为Essentials套餐付费入门级。FAQ 原文docs/content/toolkits/faq/mailchimp.md明确指出免费 Mailchimp 账户可能不足以支撑请求的工具流程。解法先确认连接配置与 server prefix 无误见问题一、二再核对目标工具在 docs/public/data/toolkits.json 中的描述看是否有套餐前置条件若确为套餐限制需用户在 Mailchimp 侧升级到 Essentials 及以上套餐。仓库工具描述中有多处套餐相关细节佐证例如MAILCHIMP_ADD_LISTAdd list注明免费 Mailchimp 账户仅限 1 个受众audience付费套餐支持多个受众MAILCHIMP_ADD_AUTOMATION注明经典自动化仅对已创建过经典自动化的付费账户开放。这些都属于「连接正确但工具因账户权限失败」的典型场景。问题四Proxy Execute 使用原始 access token 时必须同时携带 subdomain场景通过 Composio 的 Proxy Execute 能力用 Mailchimp 自定义连接数据custom connection data直接执行工具而不走 Composio 托管 OAuth 流程。要求调用/api/v3/tools/execute/proxy时val中必须同时包含access_tokenMailchimp OAuth 原始访问令牌subdomainserver prefix如us20同时请求体需要携带toolkitSlug: mailchimpauthScheme: OAUTH2FAQ 原文给出的完整参数组合如下docs/content/toolkits/faq/mailchimp.mdPOST /api/v3/tools/execute/proxy { toolkitSlug: mailchimp, authScheme: OAUTH2, val: { access_token: oauth-access-token, subdomain: us20 } }漏传subdomain是 Proxy Execute 模式下最容易被忽略的错误凭证正确但请求仍打到默认数据中心导致执行失败。需要特别说明Proxy Execute 面向「自定义连接数据」的高级用法常规场景仍建议走标准 OAuth 连接流程由 Composio 管理令牌与数据中心的绑定。问题五Mailchimp 支持触发器但使用前需核对具体事件Mailchimp 出现在 Composio 的 supported-trigger 工具包列表中当前仓库数据docs/public/data/toolkits.json显示其triggerCount为 4。实践建议FAQ 原文 docs/content/toolkits/faq/mailchimp.md使用某个具体 Mailchimp 触发器前先核对确切的触发器/事件在当前工具包版本中是否存在可在 docs/public/data/toolkits.json 的triggerCount与工具列表、或 Composio 平台工具包页面上确认若所需事件不存在通过 Composio 的请求入口request portal提交用例由平台评估并排期新增。这一策略同样适用于其他工具包的触发器接入工具包名出现在支持列表 ≠ 任意事件都可用事件粒度需要以当前版本为准。进阶Mailchimp 输出已升级为强类型响应除了上述五个 FAQ 场景仓库 changelogdocs/content/changelog/02-03-26.mdx记录了一个与 Mailchimp 工具使用强相关的演进Mailchimp 与 GitHub、Trello 一起成为首批获得强类型响应typed responses的工具包之一。该变更意味着所有 Mailchimp 工具输出返回强类型对象字段有清晰文档而非泛化的response_datablob获得更好的 IDE 自动补全与字段校验Agent 解析输出时更可靠破坏性变更提醒如果你使用latest版本且代码依赖旧的response_data结构需要更新代码适配新的类型化响应 schema。对 Agent 开发者而言这意味着接入 Mailchimp 工具后可以直接按类型化字段读取返回结果如 campaign id、list id 等减少手工解析错误。排查清单速查将上述问题整理为一份可执行的排查顺序步骤检查项正确做法错误做法1server prefix 取值取.admin.mailchimp.com之前部分如us19整段 URL 或留空2connectionConfig 字段名subdomain或旧别名dcserver_prefix被忽略回退us213Mailchimp 套餐确认目标工具是否要求 Essentials 及以上免费账户跑高级工具流程4Proxy Execute 载荷val中同时给access_tokensubdomain只给 access_token5触发器事件核对具体事件在当前版本存在仅凭工具包名在支持列表就假设全部可用总结Mailchimp 工具包接入失败的高频原因可以收敛为「三个字段、一个套餐、一个校验」subdomain字段名而非server_prefix、正确的 server prefix 值.admin.mailchimp.com之前部分、Proxy Execute 时补全subdomain以及免费/付费套餐对 API 能力的限制。这些结论均以仓库官方 FAQdocs/content/toolkits/faq/mailchimp.md、知识库文档docs/content/kb/guide/toolkits-mailchimp.mdx和源码 schemats/packages/core/src/types/connectedAccountAuthStates.types.ts为依据可在接入与排障时直接对照使用。【免费下载链接】composioComposio powers 1000 toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.项目地址: https://gitcode.com/GitHub_Trending/co/composio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考