Mailbo Help Center

Full catalogue of the 42 tools your AI client can call against Mailbo, grouped by resource.

Once Claude (or another MCP client) is connected (see Connect Claude via MCP), it can call any of the tools below. Tools needing write scope mutate workspace data; read tools are safe.

Each tool proxies to the corresponding REST endpoint, so error messages and validation rules are identical.

Workspace

Tool	Scope	What it does
`get_workspace`	read	Return workspace id + name + scopes. Connection-test.
`workspace_summary`	read	One-shot counts for contacts, tags, lists, sequences + recent purchases. Best first call for orientation.

Contacts

Tool	Scope	What it does
`list_contacts`	read	List contacts, filter by status or email substring.
`get_contact`	read	Get one contact by UUID.
`find_contact_by_email`	read	Look up a contact by email; returns `{data: null}` if not found.
`upsert_contact`	write	Create or update a contact (looked up by email). `attrs` is merged into existing custom fields by default — partial updates do NOT clear other keys. Set a value to `null` to clear that single key, or pass `attrs_mode: "replace"` for wholesale overwrite.
`update_contact`	write	Patch fields on a specific contact UUID. Same `attrs` merge semantics as `upsert_contact`.
`delete_contact`	write	Permanent delete. Prefer `unsubscribe_contact` for opt-outs.

Tool	Scope	What it does
`list_tags`	read	List all tags.
`list_custom_fields`	read	List the workspace's custom-field DEFINITIONS (key, label, type, entity) for contacts and purchases. Optional `entity` filter (`contact` or `purchase`). Use these keys when writing contact or purchase `attrs`.
`create_custom_field`	write	Create (or update) a custom-field definition. `key` is snake_case, `type` is one of text/number/date/boolean/url. Idempotent on (entity, key).
`create_tag`	write	Create a tag (idempotent by name).
`add_tags`	write	Add tag names to a contact UUID; unknown names are auto-created.
`remove_tag`	write	Remove one tag from one contact.
`quick_tag_by_email`	write	Upsert contact by email + attach tags in one call. Best when you only have the email.

Lists

Tool	Scope	What it does
`list_lists`	read	List all lists.
`create_list`	write	Create a static or dynamic list.
`add_contact_to_list`	write	Add a contact to a static list.
`remove_contact_from_list`	write	Remove a contact from a list.

Sequences

Tool	Scope	What it does
`list_sequences`	read	List sequences.
`get_sequence`	read	Get one sequence + ordered steps.
`create_sequence`	write	Create a sequence with all its steps + email content in one call.
`update_sequence`	write	Update fields; pass `steps` to replace the whole step array.
`enroll_in_sequence`	write	Enroll a contact (by email or `contact_id`).

Campaigns

Tool	Scope	What it does
`list_campaigns`	read	List campaigns, filter by status.
`get_campaign`	read	Get one campaign with body + stats.
`create_campaign`	write	Create a draft campaign. Only `name` is required — sender fields inherit from email settings. body_html shortcut wraps raw HTML as source-mode.
`update_campaign`	write	Update name, subject, from-fields, status, `scheduled_at`, body, layout. Use status `paused` / `cancelled` to halt a scheduled send.

Automations

Tool	Scope	What it does
`list_automations`	read	List automations (metadata only — no graph).
`get_automation`	read	Get one automation with its full graph.
`create_automation`	write	Create an automation with an optional full graph. Tool description embeds the full node-type catalogue so an LLM can build advanced workflows from natural language.
`update_automation`	write	Update fields; pass `graph` to swap the entire workflow.
`delete_automation`	write	Permanent delete; cascades to `automation_runs`. Prefer status `paused` if you want history preserved.

Events

Tool	Scope	What it does
`track_event`	write	Fire a lifecycle event (`pricing_viewed`, `signup_completed`, …) against a contact. Auto-creates the contact if needed.

Purchases

Tool	Scope	What it does
`list_purchases`	read	List purchases. Filter by email / `contact_id` / `source`.
`record_purchase`	write	Record a purchase. `external_id` deduplicates retries safely. Pass `attrs` (object keyed by `custom_fields.key` where `entity='purchase'`) to populate purchase custom fields. Call `list_custom_fields` first to discover valid keys.

Outbound webhooks

Tool	Scope	What it does
`list_webhooks`	read	List outbound webhook subscriptions. Secrets are not returned.
`get_webhook`	read	Get one webhook by UUID. Secret is not returned.
`create_webhook`	write	Create a subscription. Returns the HMAC `secret` ONCE in the response — store it. Events: `email.opened`, `email.clicked`, `email.bounced`, `email.complained`, `email.unsubscribed`, or `*`.
`update_webhook`	write	Update name/url/events/enabled. Pass `secret: true` to auto-rotate, or `secret: "<new>"` to set a specific value. Returns the new plaintext secret once.
`delete_webhook`	write	Permanently delete a subscription.

Unsubscribe

Tool	Scope	What it does
`unsubscribe_contact`	write	Mark an email as unsubscribed. Idempotent.

Automation graph cheat-sheet

create_automation and update_automation accept a graph object built from these node types:

Type	Purpose
`trigger`	Entry point. Exactly one per graph.
`send_email`	Send an email. Needs `data.subject` + body.
`wait`	Delay. `data: { value, unit: minutes/hours/days/weeks }`.
`add_tag`	Add a tag to the contact.
`remove_tag`	Remove a tag.
`if_has_tag`	Branch on tag membership. Edges leaving need `sourceHandle: 'yes'` or `'no'`.
`if_on_list`	Branch on list membership.
`if_filter`	Branch on a full filter (`match`: all/any, plus rules).
`end`	Terminal node.

Edges: {source, target, sourceHandle?}. The handle is required on edges leaving conditional (if_*) nodes.

Tool count

42 tools as of this writing. Restart your MCP client (or claude mcp remove mailbo && claude mcp add …) after Mailbo deploys to pick up any new tools — most clients cache the tool list from the initial tools/list call.

MCP tools reference — every tool