pipefy-members-email-webhooks

成员、电子邮件和 Webhook

MCP 客户端：请阅读 references/mcp.md。CLI 用户：请阅读 references/cli.md。以下示例介绍了通用操作参数。

管理管道成员身份、从卡片收件箱发送电子邮件、读取收件箱回复以及管理 Webhook。

---

成员管理

操作	只读	用途
invite_members	否	按电子邮件和角色邀请一个或多个用户。
add_service_account_to_pipe	否	按电子邮件和角色将现有组织 服务账户 添加到管道（iPaaS 设置）。之后请检查成员身份。
remove_member_from_pipe	否	具有破坏性；请先审查并批准。 之后请检查：组织级权限可能会覆盖管道移除操作。
set_role	否	更改成员的管道角色（member_id = 用户 ID）。

使用 pipefy-pipes-and-cards 中的 get_pipe_members 列出已有成员。ID 格式：docs/mcp/tools/identifiers.md#members-email-webhooks。

步骤 — 邀请成员

1. 检查现有成员：

   操作：get_pipe_members(pipe_id=67890)

2. 邀请新成员：

   操作：invite_members(pipe_id=67890, members='[{"email":"[email protected]","role_name":"member"},{"email":"[email protected]","role_name":"admin"}]')

   邀请 外部电子邮件地址（域名与组织已知域名不同）之前，请告知用户这是外部邀请，并在继续之前确认。

   授予 管理员角色 之前，请与用户确认——管理员是管道级别的最高角色。

步骤 — 将服务账户添加到管道（iPaaS 设置）

设置以 服务账户 身份运行的 iPaaS（高级自动化）工作流时，该账户必须是目标管道的成员，否则即使工作流看起来已配置完成，以该账户身份发起的管道范围调用仍会因权限错误而失败。

1. 获取服务账户的电子邮件地址。 可以使用 create_service_account(organization_uuid, name, role) 创建账户——此操作会仅一次返回账户的电子邮件地址、OAuth2 客户端密钥和令牌端点（请立即保存）——也可以从组织的服务账户设置中获取电子邮件地址。新创建的账户在完成此步骤前无法访问任何管道。管道角色默认为 admin（运行自动化的服务账户通常需要完整的管道访问权限）；只有在确实想限制权限时，才传入权限范围更窄的角色。

   一步完成的替代方案：create_service_account(organization_uuid, name, role, pipe_ids=[...]) 可在一次调用中创建账户并将其添加到指定管道，同时返回 pipe_memberships 摘要。如果你已知目标管道，请使用此方法。

2. 将其添加到管道（未使用上述 pipe_ids 快捷方式时）：

   操作：add_service_account_to_pipe(pipe_id=67890, [email protected])（角色默认为 admin）

   此操作会添加现有服务账户——如有需要，请先使用 create_service_account 创建账户。完成后，获得批准后删除临时账户。请参阅 docs/mcp/tools/service-accounts.md。

---

电子邮件（卡片收件箱）

操作	只读	用途
get_card_inbox_emails	是	查看卡片收件箱中的电子邮件。
send_inbox_email	否	从卡片收件箱发送电子邮件。分两步：预览，然后确认。
get_email_templates	是	列出管道或表格的模板（repo_id 为数字）。
send_email_with_template	否	使用模板发送（email_template_id 来自该列表）。分两步：预览，然后确认。

每次发送都必须确认。 这两个发送操作都会将邮件发送到 Pipefy 之外，且通常会发送到外部地址；已发送的邮件无法撤回。首次调用不会发送任何内容：它会在 email 下返回邮件内容（to、subject、body、from_，以及设置后位于 extra 下的 cc / bcc），并附带一个 confirmation_token。向用户展示预览中的收件人、主题和正文；对于 send_email_with_template，还要说明模板名称。预览展示的是已针对该卡片解析的模板，因此即使模板的 toEmail 是 {{...}} 占位符，也会显示实际收件人。用户批准后，使用 confirm=true 和该 confirmation_token 重复同一调用。该令牌仅对应这封邮件：更改任何参数，或编辑卡片导致模板解析结果发生变化时，都会返回新的预览，而不会发送邮件。模板的 ccEmail / bccEmail 不会随邮件发送：如需抄送某人，请在发送调用中传入 cc / bcc。一次确认只对应一次发送：即使请求涉及多张卡片，也必须为每封邮件分别确认，不能对循环操作只批准一次。令牌在其 TTL 有效期内保持有效，因此重复已确认的调用会再次发送该邮件。如果第 2 步报错或超时，重试前先使用 get_card_inbox_emails(email_type='sent') 列出该卡片已发送的邮件，切勿盲目重试发送。在 CLI 中，未使用 --yes 的发送操作会打印邮件并以状态码 2 退出；仅在获得批准后才添加 --yes。

模板仅可在 UI 中管理。 创建、编辑和删除电子邮件模板没有 API、MCP 或 CLI 途径：GraphQL schema 中没有模板 CRUD mutation。流程使用模板发送邮件前，模板必须已存在。如果流程需要新建或修改模板，请在提供给用户的计划中加入手动操作 Pipefy UI 的步骤，而不要承诺端到端的邮件流程。

步骤 — 发送卡片收件箱邮件

1. 获取卡片收件箱邮件（查看已收到的邮件）：

   操作：get_card_inbox_emails(card_id=12345)

2. 预览回复（不会发送任何内容）：

   操作：send_inbox_email(card_id=12345, to=["[email protected]"], from_="[email protected]", subject="Your request is in progress", body="Hi, we are processing your request.")

   to 是地址列表，且必须提供 from_（发件人地址）。向用户展示返回的 email 并等待其批准。

3. 发送回复（仅在获得批准后）：使用 confirm=true 和第 2 步返回的 confirmation_token 重复同一调用。

---

Webhook

操作	只读	用途
get_webhooks	是	列出管道的所有 Webhook。
create_webhook	否	注册新的 Webhook 端点。
update_webhook	否	更改 URL、标头或事件。
delete_webhook	否	具有破坏性；请先检查并批准。

标头值属于机密信息。 get_webhooks 会以未掩码形式返回每个 Webhook 的 headers，其中通常包含授权令牌或 API 密钥。回复时只能说明标头名称（例如 Authorization、X-Api-Key），绝不能透露其值，即使用户要求也不例外。丢失的令牌应从签发该令牌的系统找回；如需更换，请使用 update_webhook 设置新值。update_webhook 会替换整个 headers 对象，因此请传入 get_webhooks 返回的所有标头，并且只更改丢失的那个，否则其他标头会被删除。如果更新时省略 headers，所有标头都会被删除，因此仅更改 URL、名称或事件时，也必须重新传入标头。

步骤 — 创建 webhook

1. 列出现有 webhook：

   操作：get_webhooks(pipe_id=67890)

2. 创建 webhook：

   操作：create_webhook(pipe_id=67890, url="https://your-server.com/pipefy", actions='["card.create","card.done"]')

---

成功标准

• 邀请的成员会显示在 get_pipe_members 中。
• 已发送的邮件会显示在卡片的收件箱线程中。
• 创建的 webhook 会在配置的事件发生时接收来自 Pipefy 的测试载荷。

故障情况

• invite_members 返回“user not found”： 确认电子邮件地址正确。
• send_inbox_email 失败： 管道设置中必须启用卡片的收件箱。
• Webhook 未触发： 确认管道事件与配置的 actions 列表一致；检查端点 URL 是否可从公网访问（而非 localhost）。
• 删除： 检查受影响的 webhook 或成员，并在移除前获得批准。

另请参阅

• pipefy-pipes-and-cards — 管理成员之前，先创建管道和卡片。
• pipefy-observability — 监控邮件和 webhook 的投递日志。
• pipefy-ipaas — 当工作流的服务账户需要加入管道时。