企业官网建设流程全解析

Automatisch 连接 Mailchimp：OAuth 应用注册与连接配置实战指南

【免费下载链接】automatischThe open source Zapier alternative. Build workflow automation without spending time and money.项目地址: https://gitcode.com/GitHub_Trending/au/automatisch

本篇技术指南以 Automatisch 官方文档中 Mailchimp 连接配置说明 为主体，完整讲解从在 Mailchimp 侧注册 OAuth 应用、填写重定向地址与客户端凭证，到在 Automatisch 中完成连接并应用于自动化流程的每一步操作。读完本文，你将掌握 Mailchimp 连接在 Automatisch 中的完整配置流程、底层 OAuth 2.0 授权实现原理，以及连接后可用于流程的动作与触发器清单。

Mailchimp 连接概览

Mailchimp 是 Automatisch 中一个支持连接（Connection）的官方应用。在 Automatisch 中，"连接"指的是将你在第三方服务（此处为 Mailchimp）的账号凭证安全地关联到 Automatisch，从而让工作流中的触发器和动作能够以你的身份调用该服务的 API。

从 Mailchimp 应用定义 可以看出，该应用的关键配置如下：

export default defineApp({ name: 'Mailchimp', key: 'mailchimp', baseUrl: 'https://mailchimp.com', apiBaseUrl: '', iconUrl: '{BASE_URL}/apps/mailchimp/assets/favicon.svg', authDocUrl: '{DOCS_URL}/apps/mailchimp/connection', primaryColor: '#000000', supportsConnections: true, beforeRequest: [setBaseUrl, addAuthHeader], auth, triggers, dynamicData, actions, });

其中supportsConnections: true表明该应用需要先建立连接才能使用；beforeRequest中注册了setBaseUrl与addAuthHeader两个请求拦截器，前者根据账号的数据中心（datacenter）前缀拼接 API 基础地址，后者为每次 API 请求附加Bearer类型的访问令牌。authDocUrl则直接指向本文对应的文档页面。

第一步：在 Mailchimp 侧注册应用

连接使用 Mailchimp 的 OAuth 2.0 授权流程，因此你首先需要在 Mailchimp 中创建一个应用（App）以获取客户端凭证。按照官方 连接文档 的指引，操作步骤如下：

1. 登录你的 Mailchimp 账户，进入后台。
2. 点击页面右上角的账户头像，进入你的Profile（个人资料）页面。
3. 在个人资料页中点击Extras选项卡，然后选择Registered apps（已注册应用）。
4. 点击Register An App（注册应用）按钮，进入应用注册表单。
5. 填写注册表单中的相关信息（如应用名称、描述等）。
6. 将 Automatisch 中提供的OAuth Redirect URL复制到表单的Redirect URI字段中，然后点击Create（创建）按钮完成应用创建。
7. 创建完成后，将页面显示的Your Client ID值复制到 Automatisch 连接表单的Client ID字段。
8. 将Your Client Secret值复制到 Automatisch 连接表单的Client Secret字段。
9. 在 Automatisch 页面点击Submit（提交）按钮。
10. 恭喜！连接建立成功，即可在流程中开始使用该 Mailchimp 连接。

认识 Automatisch 侧的三个关键字段

当你在 Automatisch 中为 Mailchimp 添加连接时，连接表单由 auth/index.js 中的fields数组定义，共包含三个字段：

其中oAuthRedirectUrl是只读字段，其真实值由运行环境中的WEB_APP_URL变量动态注入，指向你当前 Automatisch 实例的app/mailchimp/connections/add路径。这意味着无论你是本地开发还是生产部署，重定向地址都会自动匹配你实例的域名，你只需原样复制即可。

OAuth 授权链路：从重定向到凭证验证

连接配置表单提交后，Automatisch 会依次执行授权 URL 生成与凭证验证两步，其实现都位于 auth 目录下。

生成授权 URL

generate-auth-url.js 负责构造 Mailchimp 的 OAuth 授权页面地址：

const searchParams = new URLSearchParams({ response_type: 'code', client_id: $.auth.data.clientId, redirect_uri: redirectUri, }); const url = `https://login.mailchimp.com/oauth2/authorize?${searchParams.toString()}`;

它读取连接表单中保存的clientId与自动生成的redirectUri，以authorization_code授权模式把用户引导至https://login.mailchimp.com/oauth2/authorize。用户授权后，Mailchimp 会携带code回调到重定向地址。

用授权码换取访问令牌

verify-credentials.js 完成授权码到访问令牌的交换，并向https://login.mailchimp.com/oauth2/token发起 POST 请求：

const params = new URLSearchParams({ grant_type: 'authorization_code', client_id: $.auth.data.clientId, client_secret: $.auth.data.clientSecret, redirect_uri: redirectUri, code: $.auth.data.code, }); const { data } = await $.http.post( 'https://login.mailchimp.com/oauth2/token', params.toString() );

令牌换取成功后，代码将access_token、token_type保存到连接数据中，随后调用 get-current-user.js 请求https://login.mailchimp.com/oauth2/metadata获取当前用户信息（注意该请求使用OAuth头而非Bearer头，并显式跳过默认的 base URL 与鉴权头注入）。根据元数据响应，连接数据还会记录：

• serverPrefix（取自currentUser.dc）：Mailchimp 分配给该账号的数据中心标识；
• screenName（取自currentUser.login.login_name）：账号登录名；
• 以及scope、idToken、expiresIn、refreshToken等令牌信息。

连接状态校验

is-still-verified.js 用于在连接被使用时校验其有效性：它会重新请求 metadata 接口，只要能取到user_id就认为连接仍然有效。如果令牌失效，Automatisch 会提示你重新授权。

请求拦截器：连接如何作用于每次 API 调用

连接建立后，所有 Mailchimp 动作与触发器的 API 请求都会经过 index.js 中beforeRequest注册的两个拦截器：

• set-base-url.js：从连接数据读取serverPrefix，将请求的baseURL动态设置为https://${serverPrefix}.api.mailchimp.com。由于 Mailchimp 的 API 域名按账号所属数据中心（如us1、us2等）区分，这一步保证了请求总能发往正确的数据中心节点；
• add-auth-header.js：当连接数据中存在accessToken时，为请求头附加Authorization: Bearer <accessToken>。

两个拦截器都支持通过additionalProperties（skipAddingBaseUrl、skipAddingAuthHeader）跳过默认行为，例如 metadata 请求就需要自行使用OAuth头。

连接可用的动作与触发器

建立连接后，你可以在流程编辑器中基于该连接添加 Mailchimp 的动作与触发器。依据 动作清单 与 触发器清单，可用能力如下：

动作（Actions）

其实现分别位于 actions/create-campaign/index.js 与 actions/send-campaign/index.js。

触发器（Triggers）

实现分别位于 triggers 目录下的email-opened、new-subscribers、new-unsubscribers子目录。

此外，dynamic-data 目录还提供了list-audiences、list-campaigns、list-segments-or-tags、list-templates四类动态数据加载器，用于在配置动作参数时以下拉形式拉取你账号下的受众、活动、分组/标签与模板，例如在创建活动时选择目标受众。

常见问题与排查要点

• Redirect URI 不匹配：确保 Automatisch 上的OAuth Redirect URL与 Mailchimp 应用注册表单中的Redirect URI完全一致（包括末尾路径），否则授权回调会被 Mailchimp 拒绝。
• 凭证填写位置：Client ID与Client Secret分别对应 Mailchimp Registered apps 页面展示的Your Client ID与Your Client Secret，两者不可互换或混填。
• 连接失效：访问令牌过期或用户撤销授权后，连接校验（isStillVerified）会失败，此时需要重新执行授权流程。连接数据中的refreshToken已被保存，为令牌刷新机制的实现保留了数据基础。
• 数据中心前缀：不同 Mailchimp 账号可能位于不同数据中心，serverPrefix由 metadata 接口自动获取，因此你无需手工指定 API 域名，Automatisch 会通过setBaseUrl自动拼接。

综上，Mailchimp 连接的配置本质上是标准的 OAuth 2.0 授权码流程：在 Mailchimp 注册应用拿到客户端凭证 → 在 Automatisch 填写凭证并复制重定向地址 → 授权后自动换取并保存令牌与数据中心信息 → 连接即可被流程中的动作与触发器复用。

【免费下载链接】automatischThe open source Zapier alternative. Build workflow automation without spending time and money.项目地址: https://gitcode.com/GitHub_Trending/au/automatisch