Agent Mail

Tools in the agent_mail scope, callable over space-mcp (tools/call) or space-api (REST) with a wks_live_* key that grants agent_mail.

approve_campaign_drafts

Scope: agent_mail:write

Approve personalized draft(s) so they're allowed to send. Pass draft_id for one, or campaign_id to approve ALL generated/edited drafts at once. NOTE: you (the agent) can only approve when the campaign's personalization_review='any' — if it's 'owner', a human must approve in the app.

assign_mail_signature

Scope: agent_mail:write

Assign a library signature to a sending address (use list_mail_addresses for address ids, list_mail_signatures for signature ids). Pass signature_id=null to clear the assignment so the address inherits the space default.

control_mail_campaign

Scope: agent_mail:run

Pause, resume, or cancel an email campaign. Broadcasts: pause/cancel while scheduled, resume re-schedules. Drips: pause/resume while active/paused, cancel from draft/active/paused. A campaign already fanning out ('sending') can no longer be stopped.

create_designed_mail_template

Scope: agent_mail:write

Create a DESIGNER-GRADE email template by emitting a block tree — the SAME pipeline the in-UI AI Mail designer uses. The blocks are compiled by the shared email-safe compiler, so the result automatically gets table layout, Outlook fallbacks, dark-mode flip, and mobile reflow (prefer this over create_mail_template + raw body_html, which skips all that). Returns a normal template (usable in campaigns by template_id) whose blocks also open in the visual editor. blocks: ordered array. Each = { block_type, props?, design?, slots? }. BLOCK TYPES + key props: hero { title, subtitle?, cta_label?, cta_url?, image_url?, alignment?:'left'|'center', text_overlay?:bool (image becomes full-bleed bg w/ white text), overlay_opacity?:0..0.95, background_link_url? }; text { content_md } (markdown: # ## ### , bold, italic, links, >quote, - lists); button { label, url, variant?:'solid'|'outline', font_size?:10-28, color?:hex, text_color?:hex }; image { url, alt?, link_url? }; image_with_caption { image_url, caption?, credit? }; product { image_url?, title, price?, original_price?, description?, cta_label?, cta_url?, cta_color?, cta_font_size?, layout?:'card'|'inline' }; pull_quote { quote_text, attribution?, variant?:'default'|'highlight' }; section_header { eyebrow?, title?, show_rule? }; feature_row { columns?:2|3|4, layout?:'grid'|'list', features:[{icon,title,body?}] }; social_row { links:[{platform:'facebook'|'x'|'instagram'|'youtube'|'linkedin'|'tiktok'|'website'|'email', url}] }; callout { title, body?, cta_label?, cta_url?, cta_color?, cta_variant?, button_position?:'beside'|'below' }; footer { address, show_unsubscribe? }; divider; spacer { height }; custom_html { html }; columns { column_count:2 }; flex_columns { widths:[40,60] }. CTA styling on hero/callout/product uses cta_color, cta_text_color, cta_variant, cta_size, cta_font_size. design (any block): background_color, background_image_url (+ background_image_size 'cover'|'tile'), background_overlay_opacity (0..0.95 darken scrim), background_overlay_color (+ background_overlay_angle) for gradients, text_color, border_color, padding/padding_x/padding_y/margin_top/margin_bottom (none/xs/sm/md/lg/xl/2xl), border, radius, text_align, font_size_scale (xs..4xl). NESTING: columns/flex_columns hold children via slots:[[...left blocks], [...right blocks]] (slot 0=left, 1=right). Only those two types accept slots. theme (optional, whole email): { palette?, accent_color?:hex, font?, spacing_rhythm?:'compact'|'normal'|'generous', dark_mode_variant?:'auto', page_background_color?:hex, page_background_image_url? }. Supports {{merge_tags}} like {{first_name}} in any text/subject.

create_mail_campaign

Scope: agent_mail:write

Create a DRAFT email campaign (broadcast or drip). A connected sender address is NOT required to draft — only to send. For drips pass steps (ordered). Use list_mail_addresses / list_audiences to discover ids. COLD EMAIL: pass is_outreach=true on a drip for the cold-outreach preset (stop_on_reply, 50/day cap, 9-17 Mon-Fri window — each overridable), plus optional reply_agent_id (cloud agent that takes over the thread when a recipient replies), sender_rotation_ids (mailbox rotation pool) and warmup_* (gradual daily-cap ramp). PERSONALIZATION: set personalization_enabled=true on a step so every recipient gets a unique AI-written email (step subject/body = the base template); set personalization_review ('none' auto-send | 'owner' human approves | 'any' you may approve) + personalization_context, then call generate_campaign_drafts to write them.

create_mail_signature

Scope: agent_mail:write

Create a reusable email signature in the library. html is the rendered signature as an inline-styled HTML fragment (a 'business card' — NOT a full <html> document); it is appended beneath plain 1:1 emails. Optionally set_default to make new/unassigned addresses inherit it, and detail_id to link a reusable info profile (see list_signature_details). Assign it to a specific sender with assign_mail_signature.

create_mail_template

Scope: agent_mail:write

Create a reusable email template. kind 'html' (full designed HTML email you author) or 'plain_text'. Supports {{merge_tags}} like {{first_name}}.

create_message_template

Scope: agent_mail:write

Create a reusable message template. channel: email | sms (subject is email-only). variables: [{key,label,required?,default?}] for {{merge}} tags.

create_signature_detail

Scope: agent_mail:write

Create a reusable signature detail profile (the info that fills a design). identity may include name, title, company, tagline, phone, email, website, cta_label, cta_url, logo_url, photo_url.

delete_mail_signature

Scope: agent_mail:write

Delete a library signature. Addresses that used it fall back to the space default signature.

delete_message_template

Scope: agent_mail:write

Delete a space message template.

generate_campaign_drafts

Scope: agent_mail:write

Write per-recipient AI-personalized emails for a drip campaign's personalized steps (steps with personalization_enabled). Generates up to limit (step × contact) pairs per call and returns { generated, failed, remaining } — CALL AGAIN while remaining>0 to cover everyone. Bills the space wallet. If personalization_review='none' drafts auto-send; otherwise review/approve them before (or after) starting. Safe to run before Start — drafts are keyed to contacts and reused when the campaign begins. Pass contact_ids or regenerate=true to redo specific ones.

get_brand_footer

Scope: agent_mail:read

Get the space's brand footer config — the mailing address / fine print / social links the AI email builder designs into the footer of designed & campaign emails (CAN-SPAM legal core).

get_mail_campaign

Scope: agent_mail:read

Get one email campaign, including its drip steps if it's a drip, its approval state (approval_status/submitted_at/approved_at/rejection_reason), and approval_required (whether this space gates sends behind human approval).

get_mail_signature

Scope: agent_mail:read

Get one email signature including its rendered HTML and stored design data.

get_mail_template

Scope: agent_mail:read

Get one email template including its body.

get_mail_template_blocks

Scope: agent_mail:read

Get a template's editable block tree (block_type, props, design, parent_id, parent_slot, order_index) plus its theme — so you can edit precisely and send the modified tree back via update_designed_mail_template.

get_mail_thread

Scope: agent_mail:read

Get one inbound mail thread with its messages (oldest first), including each message id (use as reply_to_message_id in send_agent_mail to reply in-thread).

get_message_template

Scope: agent_mail:read

Get one space message template including its body and variables.

list_campaign_drafts

Scope: agent_mail:read

List the per-recipient personalized drafts for a campaign: contact, subject, body_html, status (generated/edited/approved/skipped/failed) + a status rollup (counts). Filter by step_id or status. Use to review what the AI wrote before approving.

list_campaign_recipients

Scope: agent_mail:read

Per-recipient state of a mail campaign or drip: who's enrolled, current step, next send, unsubscribed/failed, and each recipient's last-message tracking (delivered/opened/clicked). Use to answer 'who opened the campaign?' or 'who should I follow up with?'.

list_campaign_replies

Scope: agent_mail:read

List everyone who REPLIED to a drip / cold-email campaign: contact, when they replied, the mail thread_id, and a snippet of their reply. Pair with get_mail_thread to read the full reply and send_agent_mail (reply_to_message_id) to answer — or set reply_agent_id on the campaign so a cloud agent answers automatically.

list_mail_addresses

Scope: agent_mail:read

List the email addresses assigned to this space (usable as campaign senders).

list_mail_campaigns

Scope: agent_mail:read

List email campaigns (broadcasts + drip sequences) in the space.

list_mail_messages

Scope: agent_mail:read

Read individual emails with per-message tracking: engagement (delivered/opened/clicked/bounced), timestamps, bounce reason. Filter by thread_id (read a conversation's messages), campaign_id, direction ('inbound' = the agent's received mail), since (ISO), or search (subject/address). Set include_body:true for body text. THIS is how you answer 'did they open my email?' for 1:1 sends.

list_mail_signatures

Scope: agent_mail:read

List email signatures in the space's signature library. is_default marks the one new/unassigned sending addresses inherit.

list_mail_suppressions

Scope: agent_mail:read

List the space-wide do-not-send list: addresses auto-suppressed after a hard bounce or spam complaint, plus manual adds. Every drip step and broadcast send skips these. Use for deliverability audits and pre-import list cleaning.

list_mail_templates

Scope: agent_mail:read

List reusable email templates in the space.

list_mail_threads

Scope: agent_mail:read

List inbound agent-mail conversations (the inbox) for the space, newest first. Use to triage incoming email; reply with send_agent_mail (reply_to_message_id from get_mail_thread).

list_mail_unsubscribes

Scope: agent_mail:read

List unsubscribes across every sending address assigned to this space (per-address: someone can unsubscribe from one sender and still receive mail from another). Includes the reason (link_click, manual, spam_complaint) and which sender they unsubscribed from.

list_message_templates

Scope: agent_mail:read

List the space's reusable message templates (email/SMS bodies from the Templates feature). Optionally filter by channel.

list_signature_details

Scope: agent_mail:read

List reusable signature detail profiles (named info bundles: name/title/company/contacts/CTA/socials) used to fill signature designs. Reference one via create_mail_signature's detail_id.

run_mail_preflight

Scope: agent_mail:read

Run the deterministic pre-flight QA check (the SAME linter behind the UI's Pre-flight button — no LLM, no cost) on a template or a whole campaign. Catches dead/empty links on buttons and CTAs, missing image alt text, undeclared {{merge_tags}}, spammy/over-long subjects, Gmail-clip size, and a missing unsubscribe on bulk sends. campaign_id checks exactly what would send (every drip step, template or inline body, as bulk). Returns per-check score 0-100, status passed/warnings/failed, and a fixable issue list. ALWAYS run this before send_mail_campaign.

send_agent_mail

Scope: agent_mail:write

Send an email from one of the space's agent-mail addresses.

send_mail_campaign

Scope: agent_mail:run

Consequential: send/schedule a broadcast (scheduled_at defaults to now) or start a drip sequence. Requires a sender address, an audience, and content on the campaign. Best practice: run_mail_preflight and send_test_mail first. If get_mail_campaign shows approval_required=true, the campaign must be approved by a human first (submit_mail_campaign_for_review).

send_test_mail

Scope: agent_mail:run

Send a REAL test copy of an email to ONE address (subject prefixed '[Test]') so a human can eyeball it in a live inbox before the campaign goes out. Content source: template_id, campaign_id (+ step_position for a drip step, default 0), or inline body_html/body_text. Sender defaults to the campaign's sender, else the space's first assigned address. Merge tags are NOT rendered in tests.

set_default_mail_signature

Scope: agent_mail:write

Mark one library signature as the space's default (the brand signature new/unassigned addresses inherit). Clears any previous default.

set_mail_address_daily_limit

Scope: agent_mail:write

Set or clear the per-address daily send ceiling (deliverability guard shared across ALL campaigns sending from that address; enforced by the scheduler and the rotation picker). Pass daily_send_limit=null to remove. Use list_mail_addresses for ids + current limits.

skip_campaign_drafts

Scope: agent_mail:write

Mark personalized draft(s) 'skipped' — those contacts get the plain step template instead of an AI-written email. Pass draft_id for one, or campaign_id (optionally step_id) to skip many.

submit_mail_campaign_for_review

Scope: agent_mail:write

Submit a campaign for human approval (approval_status='pending'), or withdraw it back to unreviewed. Use when get_mail_campaign shows approval_required=true. Approving/rejecting is owner/admin-only in the UI — an agent can only submit.

suppress_mail_address

Scope: agent_mail:write

Manually add an email address to the space-wide do-not-send list (reason 'manual'). Use to pre-clean an imported lead list — known-bad addresses never get sent to, protecting sender reputation.

unsuppress_mail_address

Scope: agent_mail:write

Remove an address from the space-wide do-not-send list (e.g. a mis-flagged temporary bounce). The address becomes sendable again — do NOT use this for spam complaints unless the owner asked.

update_brand_footer

Scope: agent_mail:write

Update the space's brand footer. Enable it and set address (postal mailing address — required for CAN-SPAM), fine print, social links, and styling. The AI email builder appends this beneath every designed/campaign email.

update_campaign_draft

Scope: agent_mail:write

Edit one recipient's personalized draft (subject and/or body_html). Marks it 'edited' — still needs approval before it sends. Use list_campaign_drafts for draft ids.

update_designed_mail_template

Scope: agent_mail:write

Edit a designer-grade template and recompile. Update name/subject/description/category/theme, and/or pass blocks to REPLACE the entire block tree (read the current tree first with get_mail_template_blocks, modify, send the full new tree). Same block vocabulary as create_designed_mail_template.

update_mail_campaign

Scope: agent_mail:write

Edit a draft/paused/scheduled email campaign. Passing steps REPLACES all drip steps. Sending controls (daily_send_cap, send_window_, frequency_cap_hours, stop_on_reply/click, reply_agent_id, sender_rotation_ids, warmup_) can ALSO be tuned while the campaign is active.

update_mail_signature

Scope: agent_mail:write

Edit a library signature (name, rendered html, design data, or linked detail profile).

update_mail_template

Scope: agent_mail:write

Edit an email template (name, subject, bodies, category, variables).

update_message_template

Scope: agent_mail:write

Edit a space message template (name, channel, subject, body, variables).