mbag.ai

Documentation

The n8n-nodes-mailbuttons community node wraps the governed agent surface (/api/v1/mcp/*) so you can build governed email flows visually in n8n.

Install

In n8n, go to Settings → Community Nodes → Install and enter:

n8n-nodes-mailbuttons

Self-hosted alternative:

cd ~/.n8n/nodes        # or your N8N_CUSTOM_EXTENSIONS path
npm install n8n-nodes-mailbuttons

Restart n8n and the Mailbuttons node appears in the node panel.

Credentials

Create a Mailbuttons API credential:

  • API URL — https://mbag.ai
  • API Key — your scoped agent token (provision a sandbox inbox with your account API key to get one — see the Claude Agent SDK guide, step 1). The token carries its own inbox scope, capabilities, and environment (sandbox/production), and is sent as an Authorization: Bearer header on every request. Treat it as a secret.

Operations

Message (List Messages, Get Message, Get Attachment Text), Thread (Get Thread), Email (Send Email), Draft (List Drafts, Get Draft), and Governance (Extract Code, Propose Sender, Request Promotion, Audit Tail). Creating a sandbox inbox and approving a held draft are deliberately human account actions, not agent tools, so they are not available in the node — approve held drafts from the dashboard.

Governed send outcomes (important)

A Send Email that is blocked or held is a normal result, not an error. The backend returns governed send outcomes as HTTP 200 bodies, and the node passes them straight through as node output data. A send can return json.status of:

  • sent — delivered.
  • blocked — a policy rule (e.g. recipient blocklist, or the token lacks send scope) stopped it. json.policy.matched_rule names the rule.
  • draft_pending_approval — the send was parked as a draft for a human to approve. json.draft_id references it.

Branch your workflow on json.status (with an IF or Switch node) — do not rely on the node erroring to detect a block.

Only genuine failures surface as a node error (NodeApiError): 401 invalid or revoked key, 403 inbox out of scope or missing capability, other 4xx/5xx. Each error body carries { error, next_step } — next_step tells the agent what to do (often: open a Request Promotion). Enable Continue On Fail to route these to a separate branch instead of stopping the workflow.