企业官网建设流程全解析

• AI 技能
• 人工智能

ActiveCampaign 是集 Email 营销自动化、CRM、联系人管理、销售管道（Deals Pipeline）、标签体系、自动化流程与邮件活动管理于一体的平台。本文基于 marketingskills 仓库中的 ActiveCampaign 集成指南 展开，结合其配套的零依赖 CLI 实现与工具注册表，系统讲解 API Token 认证、REST API v3 常用操作、关键指标字段、参数取值、限流策略，以及 AI Agent 如何通过 CLI 或直接调用 API 完成联系人同步、列表订阅、自动化触发、交易管道推进等实战任务。读完本文，你将掌握一套可直接复制运行的 ActiveCampaign 自动化操作命令集，并理解其 API 设计规律与底层实现。

能力总览

ActiveCampaign 在仓库的工具注册表（REGISTRY.md）中被归类为Email/CRM类别。根据集成指南中的 Capabilities 表，其程序化接入能力如下：

其中原生 MCP 虽不可用，但仓库的 composio 工具映射 显示可通过 Composio 为 ActiveCampaign 补充 MCP 访问能力（contacts、automations 等资源），适合需要以 MCP 协议接入的 Agent 场景。

认证方式：API Token

ActiveCampaign 使用API Token认证，要点如下：

• 请求头：Api-Token: {api_token}
• Base URL：https://{yourAccountName}.api-us1.com/api/3
• 获取位置：账户后台 Settings > Developer 选项卡
• 注意事项：每个用户拥有独立的 API Key；Base URL 也是账户特有的（同样在 Settings > Developer 中查看）

由于 Base URL 是账户专属的，且不同用户 Key 不同，正确做法是把凭证放入环境变量，由 Agent 在运行时读取，避免硬编码。仓库配套 CLI 正是遵循这一约定：

export ACTIVECAMPAIGN_API_KEY=your_api_token export ACTIVECAMPAIGN_API_URL=https://yourname.api-us1.com

在 activecampaign.js 的源码中，CLI 启动时会校验这两个环境变量，缺失即报错退出并提示ACTIVECAMPAIGN_API_KEY environment variable required/ACTIVECAMPAIGN_API_URL environment variable required。这符合仓库 CLIs 安全规范：密钥只从环境变量读取，绝不写进脚本或仓库。

安装与使用：零依赖 CLI

CLI 安装方式

仓库 tools/clis/README.md 说明所有 CLI 均为零依赖、单文件的 Node.js 脚本（要求 Node 18+），无需npm install，直接运行即可：

# 方式一：直接运行 node tools/clis/activecampaign.js contacts list --limit 20 # 方式二：全局符号链接 ln -sf "$(pwd)/tools/clis/activecampaign.js" ~/.local/bin/activecampaign activecampaign users me # 方式三：将整个目录加入 PATH export PATH="$PATH:/path/to/marketingskills/tools/clis"

命令模式与输出

所有 CLI 遵循统一命令结构{tool} <resource> <action> [options]，ActiveCampaign CLI 支持的命令族为：

输出统一为 JSON 到 stdout，便于jq管道处理或写入文件（参见 tools/clis/README.md）：

node tools/clis/activecampaign.js contacts list --limit 20 | jq '.contacts[].email'

CLI 还支持--limit/--offset分页参数（默认 limit=20、offset=0，见 activecampaign.js），以及关键的--dry-run预览模式：只打印将发送的请求（含方法、URL、脱敏为***的请求头、body）而不真正发起网络调用，适合 Agent 在执行危险写操作前自检。

环境变量安全规范

仓库的 CLI 认证表（tools/clis/README.md）明确 ActiveCampaign 使用两个环境变量：ACTIVECAMPAIGN_API_KEY与ACTIVECAMPAIGN_API_URL。安全要点：

• 密钥存于 shell 配置文件（~/.zshrc、~/.bashrc）或.env文件；
• .env已被 gitignore，但提交前仍需二次确认；
• 对任何命令先加--dry-run预览请求；
• 切勿在脚本或提交记录中硬编码密钥。

联系人管理（Contacts）

获取当前用户

GET https://{account}.api-us1.com/api/3/users/me

CLI 对应：activecampaign users me。

查询联系人列表

# 分页查询 GET https://{account}.api-us1.com/api/3/contacts?limit=20&offset=0 # 按邮箱精确过滤 GET https://{account}.api-us1.com/api/3/contacts?email=user@example.com # 按姓名文本搜索 GET https://{account}.api-us1.com/api/3/contacts?search=Jane

CLI 的contacts list在 activecampaign.js 中会把--email、--search、--list-id、--status等参数拼接到查询串上，其中--list-id映射为listid、--status映射为status。

创建联系人

POST https://{account}.api-us1.com/api/3/contacts { "contact": { "email": "user@example.com", "firstName": "Jane", "lastName": "Doe", "phone": "+15551234567" } }

CLI：activecampaign contacts create --email user@example.com --first-name Jane --last-name Doe --phone +15551234567（--email为必填，见 activecampaign.js）。

更新联系人

PUT https://{account}.api-us1.com/api/3/contacts/{contactId} { "contact": { "firstName": "Updated", "lastName": "Name" } }

CLI：activecampaign contacts update --id 123 --first-name Updated --last-name Name。

同步联系人（创建或更新，幂等）

POST https://{account}.api-us1.com/api/3/contact/sync { "contact": { "email": "user@example.com", "firstName": "Jane", "lastName": "Doe" } }

这是 Agent 做数据同步时的首选端点：以 email 为唯一键，存在则更新、不存在则创建，天然幂等。CLI：activecampaign contacts sync --email user@example.com --first-name Jane --last-name Doe。

删除联系人

DELETE https://{account}.api-us1.com/api/3/contacts/{contactId}

CLI：activecampaign contacts delete --id 123。

列表管理（Lists）与订阅状态

查询列表

GET https://{account}.api-us1.com/api/3/lists?limit=20&offset=0

CLI：activecampaign lists list，或按 ID 查询activecampaign lists get --id 1。

创建列表

POST https://{account}.api-us1.com/api/3/lists { "list": { "name": "Newsletter", "stringid": "newsletter", "sender_url": "https://example.com", "sender_reminder": "You signed up for our newsletter." } }

CLI：activecampaign lists create --name Newsletter --string-id newsletter --sender-url https://example.com --sender-reminder "You signed up for our newsletter."（--name必填）。

订阅 / 退订联系人

订阅与退订共用 junction 端点/contactLists，通过status字段区分：

# 订阅（status: 1） POST https://{account}.api-us1.com/api/3/contactLists { "contactList": { "list": "1", "contact": "1", "status": 1 } } # 退订（status: 2） POST https://{account}.api-us1.com/api/3/contactLists { "contactList": { "list": "1", "contact": "1", "status": 2 } }

CLI 对应子命令：activecampaign lists subscribe --list-id 1 --contact-id 1与activecampaign lists unsubscribe --list-id 1 --contact-id 1。源码中订阅硬编码status: 1、退订硬编码status: 2（见 activecampaign.js），与集成指南的 Contact List Status 参数表一致。

Contact List Status 取值（集成指南参数表）：

邮件活动（Campaigns）

# 分页列出邮件活动 GET https://{account}.api-us1.com/api/3/campaigns?limit=20&offset=0

CLI：activecampaign campaigns list/activecampaign campaigns get --id 1。

Campaign 关键指标字段（集成指南 Key Metrics）：

交易管道（Deals / CRM）

查询交易

# 分页列出 GET https://{account}.api-us1.com/api/3/deals?limit=20&offset=0 # 按管道阶段过滤 GET https://{account}.api-us1.com/api/3/deals?filters[stage]=1 # 按负责人过滤 GET https://{account}.api-us1.com/api/3/deals?filters[owner]=1

CLI 的deals list支持--search、--stage（映射为filters[stage]）、--owner（映射为filters[owner]），见 activecampaign.js。

创建交易

POST https://{account}.api-us1.com/api/3/deals { "deal": { "title": "New Enterprise Deal", "value": 50000, "currency": "usd", "group": "1", "stage": "1", "owner": "1", "contact": "1" } }

CLI：activecampaign deals create --title "New Enterprise Deal" --value 50000 --currency usd --pipeline 1 --stage 1 --owner 1 --contact-id 1（--title必填，--pipeline映射为deal.group，见 activecampaign.js）。

更新交易（推进阶段 / 调整金额）

PUT https://{account}.api-us1.com/api/3/deals/{dealId} { "deal": { "stage": "2", "value": 75000 } }

CLI：activecampaign deals update --id 1 --stage 2 --value 75000。注意更新子命令还支持--status，内部通过Number()转为整数（activecampaign.js），对应 Deal Status 枚举。

Deal 关键字段（集成指南 Key Metrics）：

Deal Status 取值（集成指南参数表）：

管道（Deal Groups / Pipelines）

GET https://{account}.api-us1.com/api/3/dealGroups?limit=20&offset=0

CLI：activecampaign pipelines list，其实现正是请求/dealGroups端点（activecampaign.js）。

自动化（Automations）

查询自动化流程

GET https://{account}.api-us1.com/api/3/automations?limit=20&offset=0

CLI：activecampaign automations list。

将联系人加入自动化流程

POST https://{account}.api-us1.com/api/3/contactAutomations { "contactAutomation": { "contact": "1", "automation": "1" } }

CLI：activecampaign automations add-contact --id 1 --contact-id 1。注意源码明确提示--contact-id需要的是联系人 ID 而非邮箱（activecampaign.js），这是 Agent 集成时最容易踩的坑——应先用contacts list --email查出 ID 再传入。

标签体系（Tags）

查询标签

GET https://{account}.api-us1.com/api/3/tags?limit=20&offset=0

CLI：activecampaign tags list [--search 关键词]。

创建标签

POST https://{account}.api-us1.com/api/3/tags { "tag": { "tag": "VIP Customer", "tagType": "contact" } }

CLI：activecampaign tags create --name "VIP Customer" --type contact（--type默认contact，见 activecampaign.js）。

给联系人打标签

POST https://{account}.api-us1.com/api/3/contactTags { "contactTag": { "contact": "1", "tag": "1" } }

CLI：activecampaign tags add-to-contact --tag-id 1 --contact-id 1，移除则用tags remove-from-contact --id {contactTagId}（注意此时传的是 contactTag 关联记录 ID）。

Tag Types 取值（集成指南参数表）：

Webhook 与外部事件驱动

查询 Webhook

GET https://{account}.api-us1.com/api/3/webhooks?limit=20&offset=0

创建 Webhook

POST https://{account}.api-us1.com/api/3/webhooks { "webhook": { "name": "Contact Updated", "url": "https://example.com/webhook", "events": ["subscribe", "unsubscribe"], "sources": ["public", "admin", "api", "system"] } }

CLI：activecampaign webhooks create --name "Contact Updated" --url https://example.com/webhook --events subscribe,unsubscribe --sources public,admin,api,system。源码中--events与--sources使用逗号分隔并split(',')解析，默认事件为subscribe、默认来源为["public","admin","api","system"]（activecampaign.js）。

Webhook 是"基于外部事件触发自动化"的关键机制：Agent 可以在自有后端注册回调，订阅subscribe、unsubscribe等事件，实现与 ActiveCampaign 的双向联动。

API 设计规律

集成指南的 API Pattern 一节总结了 ActiveCampaign REST API v3 的四个核心规律，理解它们能让 Agent 举一反三：

1. 资源包裹（Resource Wrapping）：所有写操作的请求体都包裹在资源对象内，如{ "contact": {...} }、{ "deal": {...} }；
2. 响应结构：响应包含资源对象本身 + 元数据；
3. Junction 端点：关联资源通过连接端点管理，如/contactLists（联系人↔列表）、/contactTags（联系人↔标签）、/contactAutomations（联系人↔自动化）。凡是"两个资源之间的关系"，几乎都走这类端点；
4. Base URL 账户专属 +limit/offset分页：所有列表端点统一使用limit（默认 20）与offset分页参数。

常见查询参数（集成指南参数表）：

这套规律在 CLI 源码中体现得极为一致：api()封装函数统一处理请求头（Api-Token、Content-Type: application/json、Accept: application/json）与 JSON 序列化/解析，非 JSON 响应会回退为{ status, body }（activecampaign.js）。

限流策略

集成指南明确列出限流规则，Agent 编排批量任务时必须遵守：

• 每账户每秒 5 个请求；
• 限流作用于同一账户下的所有 API 用户（即多用户共享配额）；
• 触发 429 响应时，响应头携带Retry-After，应据此退避重试。

这意味着批量同步、批量打标签等操作需要做限速编排（例如引入节流或批量窗口），否则会很快触发 429。

适用场景

集成指南归纳了 ActiveCampaign 的典型适用场景：

• 需要复杂条件分支的营销自动化流程；
• 带交易管道管理的 CRM；
• 基于标签与分群的联系人管理；
• 邮件活动的创建与效果追踪；
• 基于外部事件触发自动化；
• 与营销联动的B2B 销售管道追踪。

在仓库中，ActiveCampaign 被 revops 技能 列为"面向中小企业的营销自动化与潜在客户评分"工具，其集成指南也关联了emails、lifecycle-marketing、crm-integration、sales-pipeline、marketing-automation等技能方向——Agent 在规划邮件序列、生命周期营销或销售管道相关任务时，可直接参考 emails 技能 的序列设计方法论，再通过本文的 API/CLI 操作落地执行。

实战组合示例

结合上述全部操作，一个典型的 Agent 工作流可以这样编排：

# 1. 幂等同步联系人 activecampaign contacts sync --email jane@example.com --first-name Jane --last-name Doe # 2. 查询联系人 ID（供后续命令使用） CONTACT_ID=$(activecampaign contacts list --email jane@example.com | jq -r '.contacts[0].id') # 3. 订阅到 Newsletter 列表 activecampaign lists subscribe --list-id 1 --contact-id "$CONTACT_ID" # 4. 打上 VIP 标签 TAG_ID=$(activecampaign tags list --search VIP | jq -r '.tags[0].id') activecampaign tags add-to-contact --tag-id "$TAG_ID" --contact-id "$CONTACT_ID" # 5. 加入自动化流程 activecampaign automations add-contact --id 1 --contact-id "$CONTACT_ID" # 6. 创建一条交易并推进阶段 activecampaign deals create --title "New Enterprise Deal" --value 50000 --currency usd --pipeline 1 --stage 1 --owner 1 --contact-id "$CONTACT_ID" activecampaign deals update --id 1 --stage 2 --value 75000

执行前可使用--dry-run逐条预览请求，确认无误后再真正发起调用。整个过程中，联系人生命周期、订阅状态、标签分群、自动化触发与销售管道推进全部通过统一认证、统一 CLI 语法完成，非常适合作为 AI Agent 的自动化脚本沉淀。

相关文件索引

• 集成指南：本文主体所依据的完整操作手册
• CLI 实现：零依赖 Node.js CLI，全部命令的源码依据
• CLI 使用说明：安装方式、环境变量认证表、命令模式与输出规范
• 工具注册表：ActiveCampaign 在仓库工具索引中的条目（Email/CRM 类别）
• Composio 工具映射：为 ActiveCampaign 补充 MCP 访问能力的途径
• revops 技能：将 ActiveCampaign 用于营销自动化与潜在客户评分的场景说明

• AI 技能
• 人工智能