pipefy-members-email-webhooks

メンバー、メール、Webhook

MCP クライアント：［references/mcp.md](references/mcp.md)をお読みください。CLI ユーザー：［references/cli.md](references/cli.md)をお読みください。以下の例では、共通の操作引数について説明します。

パイプのメンバーを管理し、カードの受信トレイからメールを送信し、受信トレイへの返信を読み取り、Webhook を管理します。

---

メンバー管理

操作	読み取り専用	目的
invite_members	いいえ	メールアドレスとロールを指定して、1 人以上のユーザーを招待します。
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](https://github.com/pipefy/ai-toolkit/blob/main/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"}]')

   外部のメールアドレス（組織で確認済みのドメインとは異なるドメイン）を招待する前に、外部への招待であることをユーザーに伝え、実行前に確認してください。

   admin ロールを付与する前に、ユーザーに確認してください。admin はパイプレベルで最も高いロールです。

手順 — サービスアカウントをパイプに追加する（iPaaS の設定）

サービスアカウントで実行する iPaaS（Advanced Automations）フローを設定する際、対象のパイプにそのアカウントをメンバーとして追加する必要があります。追加されていない場合、フローが正しく設定されているように見えても、そのアカウントのIDで行うパイプスコープの呼び出しは権限エラーになります。

1. サービスアカウントのメールアドレスを取得します。 create_service_account(organization_uuid, name, role) で作成すると、アカウントのメールアドレスに加え、OAuth2 クライアントシークレットとトークンエンドポイントが一度だけ返されます（すぐに保存してください）。または、組織のサービスアカウント設定からメールアドレスを取得してください。新しく作成したアカウントは、この手順を行うまでパイプにアクセスできません。パイプロールのデフォルトは admin です（オートメーションを実行するサービスアカウントには、通常、パイプへのフルアクセスが必要です）。意図的にアクセスを制限する場合にのみ、より制限されたロールを指定してください。

   1 回の操作で設定する方法：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](https://github.com/pipefy/ai-toolkit/blob/main/docs/mcp/tools/service-accounts.md)を参照してください。

---

メール（カードの受信トレイ）

操作	読み取り専用	目的
get_card_inbox_emails	はい	カードの受信トレイにあるメールを読み取ります。
send_inbox_email	いいえ	カードの受信トレイからメールを送信します。プレビューしてから確認する2段階の操作です。
get_email_templates	はい	パイプまたはテーブルのテンプレートを一覧表示します（repo_id は数値）。
send_email_with_template	いいえ	テンプレートを使って送信します（email_template_id はその一覧から指定します）。プレビューしてから確認する2段階の操作です。

送信するたびに確認してください。 どちらの送信操作も、Pipefy の外部へメールを配信し、多くの場合、外部アドレスに送信します。送信したメールは取り消せません。最初の呼び出しでは何も送信されません。confirmation_token とともに、email の下にメッセージ（to、subject、body、from_、設定されている場合は extra の下に cc / bcc）が返されます。プレビューに表示された宛先、件名、本文をユーザーに提示してください。send_email_with_template の場合は、テンプレート名も伝えてください。プレビューはカードに対してテンプレートを解決済みのため、テンプレートの toEmail が {{...}} のプレースホルダーでも、実際の宛先が表示されます。ユーザーの承認後、同じ呼び出しを confirm=true とその confirmation_token を指定して繰り返してください。このトークンはその1通だけを対象とします。引数を変更した場合、またはテンプレートの解決結果が変わるカードの編集が行われた場合は、送信されず、新しいプレビューが返されます。テンプレートの ccEmail / bccEmail は送信されません。誰かにコピーを送るには、送信呼び出しで cc / bcc を渡してください。確認1回につき送信1回です。複数のカードを対象とするリクエストでも、メールごとに確認が必要であり、ループ全体に対する承認はできません。トークンは TTL の間有効なため、確認済みの呼び出しを繰り返すと、メールが再送信されます。ステップ2でエラーまたはタイムアウトが発生した場合は、再試行する前に get_card_inbox_emails(email_type='sent') でカードの送信済みメールを一覧表示し、送信を確認せずに再試行しないでください。CLI では、--yes を指定せずに送信するとメールが表示され、終了コード2で終了します。承認を得た後にのみ --yes を追加してください。

テンプレートの操作は UI のみです。 メールテンプレートの作成、編集、削除には API、MCP、CLI の手段がありません。GraphQL スキーマにはテンプレートの CRUD ミューテーションがないためです。フローからテンプレートを使って送信する前に、テンプレートが作成されている必要があります。新しいテンプレートや変更済みのテンプレートが必要な場合は、エンドツーエンドのメールフローが可能だと約束するのではなく、ユーザーに提示する計画に 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 — フローのサービスアカウントにパイプのメンバーシップが必要な場合に使用します。