MCP Tool Reference

The hosted connector at https://flomailr.com/api/mcp offers 35 tools when you sign in over OAuth, and 33 when you connect with an API key (the two workspace tools are left out). Your AI app chooses the tools. You normally never name them yourself, but this page shows what exists and what each one needs.

See Connect Your AI to set up the connection.

A design is a Flomailr BlockDoc, a JSON document { version: 1, settings, blocks }. Where a tool takes doc, it accepts the object or a JSON string. You rarely need to write one by hand: compose_email builds it from sections.

Actions such as saving drafts, sending, suppression changes and brand updates are written to the activity log. See Sending Safely with AI.

Design

Tool	What it does	Key inputs
get_design_kit	Returns the themes, the section patterns and your brand kit. Read-only. Call it first when designing	none
compose_email	Builds a complete email from an ordered list of sections, using a theme and your brand kit. With save it creates a draft and returns its id	sections (1 to 20), theme, useBrand, preheader, save: { name, subject, campaignId? }
restyle_email	Re-skins a design into a theme or your brand without changing content or structure. With campaignId it updates the draft	campaignId or doc, theme, useBrand
preview_email	Shows the real rendered email in the chat with desktop, mobile and dark views, plus the audit grade and problems. Read-only	campaignId (preferred) or doc, subject
render_email_preview	Supplies the HTML to the preview view. Used by the view itself, not by agents	campaignId or doc, subject
screenshot_email	Renders the email in a real browser and returns screenshots the AI can look at, to check the design itself. Read-only	campaignId (preferred) or doc, device (desktop or mobile), maxFrames (1 to 4)
get_campaign	Loads a campaign. The default outline lists each block's id, type and a one-line summary. Read-only	campaignId, format (outline or full)
edit_campaign	Applies small edits to a draft by block id, all or nothing, and returns the new outline and audit	campaignId, ops (up to 50), subject, name

compose_email sections use these patterns: header, hero, text, features, products, articles, testimonial, stats, cta, event, image, countdown, table, signoff, footer, divider, spacer. Themes: clean, editorial, studio, hearth, midnight, poster, fresh, mono, luxe. Details are in Designing Emails with AI.

edit_campaign operations: update, remove, move, insert, settings, restyle.

Brand

Tool	What it does	Key inputs
get_brand	Returns the workspace brand kit, or null. Read-only	none
set_brand	Replaces the brand kit. Owners and admins only	colors (primary required), name, websiteUrl, logoUrl, logoWidth (40 to 600), headingFont, bodyFont, baseTheme, voice, socials (up to 10)
import_brand_from_url	Reads a website and proposes a brand kit with logo candidates and the evidence for each value. Saves only if asked, and saving needs an owner or admin	url, save (default false)

Campaigns and content

Tool	What it does	Key inputs
save_campaign	Saves a BlockDoc as a draft campaign. Never sends or schedules. Returns the campaign id, a builder link and a grade	name, subject, doc, campaignId (to update a draft)
list_campaigns	Lists campaigns, most recent first	status (DRAFT, SCHEDULED, SENDING, SENT), limit (default 20, up to 100)
import_html_campaign	Saves finished HTML as a draft with the markup stored exactly as given. Does not send	html, name, subject, text, campaignId
check_links	Fetches every link and image in some HTML or a stored campaign and reports the HTTP status, to catch dead links and blocked images	html or campaignId
upload_asset	Uploads an image to the workspace library and returns a permanent public URL. PNG, JPEG, GIF or WebP up to 5 MB. SVG is refused	filename, contentBase64
list_assets	Lists uploaded images with their URLs, so they can be reused	query, limit (default 30, up to 100)

Saving, composing and editing only ever touch drafts. A scheduled, sending or sent campaign cannot be changed through the connector.

Drafting tools that need no account data

These work on a design you give them and read nothing from your workspace.

Tool	What it does	Key inputs
render_email	Renders a BlockDoc to the final email-safe HTML, using the same renderer as the app	doc
render_plaintext	Renders a BlockDoc to a plain-text alternative	doc
audit_email	Lints a design for deliverability, accessibility, spam risk and content. Returns a 0 to 100 score, an A to F grade and findings	doc, subject
preview_personalization	Fills merge tags from a sample contact and reports which tags resolved, were empty or were unknown	doc, contact (email, firstName, lastName), subject
scaffold_email	Builds a valid BlockDoc from a compact list of block specs, for when no section pattern fits	blocks, settings
list_block_types	Lists every block type with its default props	none

Workspaces (OAuth only)

Tool	What it does	Key inputs
list_workspaces	Lists the workspaces your account belongs to, with contact, list and campaign counts, and which one is active	none
switch_workspace	Points the connector at another workspace. It does not change the workspace open in your browser	workspace (id or exact name)

Sending and safety checks

Tool	What it does	Key inputs
get_send_policy	Returns the server-enforced rules: the daily cap and what is left, blocked domains, the suppression check, quiet hours, and whether dry run is forced	none
check_send_readiness	A go, caution or no-go report on domain authentication (SPF, DKIM, DMARC), the sending provider's account health, recent bounce and complaint rates against the suspend thresholds, and monthly quota	domain (defaults to your custom domain)
score_email	Scores spam and compliance risk of a draft: trigger phrases, image-to-text ratio, link count, subject problems, unsubscribe handling	doc, subject, hasListUnsubscribe
check_compliance	Checks a campaign or draft for CAN-SPAM and GDPR readiness: unsubscribe, postal address, sender identity and, with a list, recorded consent	campaignId, or doc and subject, plus physicalAddress, listId
send_campaign	Sends an existing campaign to its list through the guarded pipeline. Dry run by default	campaignId, dryRun (default true), confirm, overrideQuietHours, idempotencyKey
send_email	Sends a personal or one-to-one email to 1 to 5 recipients. Dry run by default	to, subject, one of doc, html or body, replyTo, dryRun (default true), confirm, idempotencyKey

How the guards work is on Sending Safely with AI.

Audience and results

Tool	What it does	Key inputs
get_campaign_performance	Returns a sent campaign's sends, opens, clicks, bounces, complaints and unsubscribes with rates, any A/B split, and a suggested next step	campaignId
get_recipient_engagement	Returns a group of recipients (hard bounced, complained, clicked, or did not open) with suggested suppressions	cohort (bounced, complained, unengaged, clicked, all), campaignId, limit (default 100, up to 500)
manage_suppression_list	Lists or checks the suppression list, or adds or removes addresses. Adding and removing need confirm: true and an owner or admin over OAuth	action (list, check, add, remove), emails, reason, note, confirm, idempotencyKey
get_action_log	Returns the audit trail of tool actions, filterable by action, campaign and time	action, campaignId, since (ISO time), limit (default 50, up to 200)

get_recipient_engagement needs a campaignId for the clicked and unengaged groups. Suppression reasons are MANUAL, HARD_BOUNCE, COMPLAINT and GLOBAL_UNSUBSCRIBE, and MANUAL is the default.

Prompt

The connector also offers one prompt, design_email. It takes a brief and walks the AI through the design workflow: read the design kit, pick a theme, compose, preview, and fix any errors. It tells the AI not to send anything without your explicit go-ahead.

The email preview

preview_email shows the email inside the chat as an interactive view. Your AI app has to support interactive MCP views for it to appear. Claude does, and asks you to allow it the first time. If a client cannot show it, the tool also returns a link that opens the draft in the visual builder.