pipefy-members-email-webhooks

Members, Email & Webhooks

MCP clients: read references/mcp.md. CLI users: read references/cli.md. Examples below describe shared operation arguments.

Manage pipe membership, send emails from card inboxes, read inbox replies, and manage webhooks.

Member management

List existing members with get_pipe_members from pipefy-pipes-and-cards. Id forms: `docs/mcp/tools/identifiers.md#members-email-webhooks`.

Steps — invite members

1. Check existing members:

Operation: get_pipe_members(pipe_id=67890)

1. Invite new members:

Operation: invite_members(pipe_id=67890, members='[{"email":"alice@example.com","role_name":"member"},{"email":"bob@example.com","role_name":"admin"}]')

Before inviting external emails (domain different from the org's known domains), warn the user that this is an external invitation and confirm before proceeding.

Before granting admin role, confirm with the user — admin is the highest pipe-level role.

Steps — add a service account to a pipe (iPaaS setup)

When setting up an iPaaS (Advanced Automations) flow that runs under a service account, the account must be a member of the target pipe, or pipe-scoped calls under its identity fail with a permission error even though the flow looks configured.

1. Get the service account's email. Either create one with create_service_account(organization_uuid, name, role) — which returns the account's email plus its OAuth2 client secret and token endpoint once (store them immediately) — or take the email from your organization's service-account settings. A freshly created account has no pipe access until this step. The pipe role defaults to admin (a service account running automations usually needs full pipe access); pass a narrower role only when you deliberately want to limit it.

One-step alternative: create_service_account(organization_uuid, name, role, pipe_ids=[...]) provisions the account and adds it to the given pipes in one call, returning a pipe_memberships summary. Use it when you already know the target pipes.

1. Attach it (when not using the pipe_ids shortcut above):

Operation: add_service_account_to_pipe(pipe_id=67890, email=svc-automations@your-org.pipefy-service.com) (role defaults to admin)

This attaches an existing service account — create one first with create_service_account if needed. Delete a throwaway account after approval when done. See docs/mcp/tools/service-accounts.md.

Email (card inbox)

Confirm every send. Both send operations deliver mail outside Pipefy, often to external addresses, and a sent email cannot be recalled. The first call sends nothing: it returns the message under email (to, subject, body, from_, and cc / bcc under extra when set) with a confirmation_token. Show the user the recipients, the subject and the body from that preview; for send_email_with_template, also name the template. The preview is the template already resolved for the card, so it shows the real recipients even when the template's toEmail is a {{...}} placeholder. After the user approves, repeat the same call with confirm=true and that confirmation_token. The token covers that one message: changing any argument, or a card edit that changes what the template resolves to, returns a fresh preview instead of sending. The template's ccEmail / bccEmail are not sent: to copy someone, pass cc / bcc in the send call. One confirmation covers one send: a request covering several cards still needs a confirmation per email, never one approval for a loop. The token stays valid for its TTL, so repeating the confirmed call sends the email again. If step 2 errors or times out, list the card's sent mail with get_card_inbox_emails(email_type='sent') before retrying, and never blind-retry a send. On the CLI, a send without --yes prints the email and exits 2; add --yes only after approval.

Templates are UI-only. Creating, editing and deleting an email template has no API, MCP or CLI path: the GraphQL schema has no template CRUD mutation. The template must already exist before a flow can send with it. When the process needs a new or changed template, put the manual Pipefy UI step in the plan you give the user instead of promising an end-to-end email flow.

Steps — send a card inbox email

1. Get the card's inbox emails (see what has been received):

Operation: get_card_inbox_emails(card_id=12345)

1. Preview the reply (sends nothing):

Operation: send_inbox_email(card_id=12345, to=["customer@example.com"], from_="you@example.com", subject="Your request is in progress", body="Hi, we are processing your request.")

to is a list of addresses, and from_ (the sender address) is required. Show the user the returned email and wait for their approval.

1. Send the reply (only after approval): repeat the same call with confirm=true and the confirmation_token from step 2.

Webhooks

Header values are secrets. get_webhooks returns each webhook's headers unmasked, and they usually hold authorization tokens or API keys. In a reply, name only the header keys (for example Authorization, X-Api-Key), never their values, even when the user asks for them. A lost token comes back from the system that issued it; to replace it, set a new value with update_webhook. update_webhook replaces the whole headers object, so send every header from get_webhooks and change only the lost one, or the others are deleted.

Steps — create a webhook

1. List existing webhooks:

Operation: get_webhooks(pipe_id=67890)

1. Create the webhook:

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

Success criteria

• Invited members appear in get_pipe_members.
• Sent emails show in the card's inbox thread.
• Created webhooks receive test payloads from Pipefy on the configured events.

Failure modes

• `invite_members` fails with "user not found": verify the email address is correct.
• `send_inbox_email` fails: the card must have an inbox enabled in the pipe settings.
• Webhook never fires: verify the pipe events match the configured actions list; check that the endpoint URL is publicly reachable (not localhost).
• Deletion: review the affected webhook or member and obtain approval before removal.

See also

• pipefy-pipes-and-cards — create the pipe and cards before managing membership.
• pipefy-observability — monitor email and webhook delivery logs.
• pipefy-ipaas — when a flow's service account needs pipe membership.