StateSet API Docs

StateSet Mail ships a Model Context Protocol server, so any MCP-capable client — Claude Desktop, Cursor, Claude Code, the Anthropic SDK — can drive every marketing and inbox operation as native tools. The server advertises tools, resources, and prompts in its initialize response, so clients enable the Resources panel and Prompts catalog in their UI.

Transports

stdio — recommended for desktop clients

stateset-mail-mcp is a second binary that reads newline-delimited JSON-RPC from stdin and writes responses to stdout, logging to stderr. It reads the same environment variables as the main HTTP server — point both binaries at the same SQLite file and the MCP server sees everything the HTTP API has touched. All tools dispatch in-process, so there is no HTTP round-trip. Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "stateset-mail": {
      "command": "/usr/local/bin/stateset-mail-mcp",
      "env": {
        "DATABASE_URL":           "sqlite:///Users/you/.stateset-mail/data/mail.db",
        "STATESET_MAIL_API_KEYS": "anything-nonempty-the-stdio-binary-doesnt-auth",
        "DEFAULT_FROM":           "Agent <agent@example.com>",
        "SMTP_HOST":              "smtp.example.com",
        "SMTP_USERNAME":          "agent@example.com",
        "SMTP_PASSWORD":          "...",
        "PUBLIC_BASE_URL":        "https://mail.example.com"
      }
    }
  }
}

Restart the client and the tools are live in the next chat.

HTTP — recommended for remote clients

POST /v1/mcp accepts a single JSON-RPC request and returns a single response, with the same bearer-token auth as the rest of /v1. Use this when the MCP client lives on a different machine from the deployment.

curl -sS -X POST -H "Authorization: Bearer $KEY" \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' \
  https://mail.example.com/v1/mcp | jq '.result.tools[].name'

The tool context carries tenant identity, so a multi-tenant deployment scopes calls correctly.

Tools

A tools/list returns 44 tools: 26 marketing, and 18 covering the agent inbox.

Profiles, lists and segments

Tool	Purpose
`upsert_profile`	Create or update a contact by email; `properties` is JSON-merged with what is there
`find_profile`	Look one up by email; `null` when there is no match
`list_recent_profiles`	The most recently updated profiles
`create_list`	Create a static list
`list_lists`	Every list, with member counts
`add_to_list`	Add a profile to a list, creating the profile if it does not exist
`upsert_segment`	Create or update a saved segment by name
`list_segments`	Every saved segment
`preview_segment`	Evaluate a definition and return the matching count before you use it

Templates and campaigns

Tool	Purpose
`upsert_template`	Create or update a Handlebars template; pass `mjml_source` to compile from MJML
`list_templates`	Every template
`render_template_preview`	Render against a real or fake profile to read the final subject, HTML and text
`create_campaign`	Create a campaign against a list or segment; returns it in `draft`
`send_campaign`	Launch a draft; the worker fans out and respects suppressions
`list_campaigns`	Recent campaigns
`get_campaign_stats`	Live counters — recipients, sent, failed, suppressed, opens, clicks
`get_campaign_timeseries`	Bucketed series for opens, clicks, sent, bounced or unsubscribed

Sending, flows and events

Tool	Purpose
`send_email`	One transactional send; returns the queued message id
`upsert_flow`	Create or update an event-triggered flow by name
`list_flows`	Every flow
`track_event`	Record an event such as `order.placed`; fires any flow triggered by it
`list_recent_events`	Recent events across all profiles
`suppress_email` / `unsuppress_email`	Add to or remove from the suppression list
`create_webhook_subscription`	Subscribe a URL to platform events; `['*']` matches everything
`list_recent_activity`	The activity log of state-changing operations

The agent inbox

Tool	Purpose
`list_conversations`	Threaded inbound and outbound messages, filterable for triage
`get_conversation`	One conversation with its full chronological thread
`reply_to_conversation`	Reply into a thread, threading off the most recent inbound message
`set_conversation_status`	`open`, `pending`, `closed` or `snoozed` — snoozing needs `snooze_until`
`assign_conversation`	Assign to an agent, or unassign by omitting the assignee
`tag_conversation`	Add and remove tags
`mark_conversation_read` / `mark_conversation_unread`	Read state
`search_messages`	Full-text search across inbound and outbound messages
`list_inbox`	Received email, newest first, optionally by mailbox
`read_inbox_message`	One message in full: body, attachments, bounce detail
`fetch_attachment`	One attachment as base64, by message id and index
`create_mailbox`	Register an address on your managed domain
`get_mailbox` / `list_mailboxes`	Look one up, or list them all
`support_automation_configure`	Link your support-email domain to your own workflow engine
`support_automation_get`	Read that configuration
`support_automation_test`	Send a synthetic signed `inbox.received` ping to the configured URL

Longer treatment of the inbox tools lives in Conversations.

The same 14-function marketing surface is also available as plain OpenAI- and Anthropic-format tool schemas at GET /v1/tools, if you’d rather wire it into an agent directly than go through MCP.

Resources

resources/list enumerates recently-touched entities; resources/read returns the full JSON body for one. Resources let a model read state without burning a tool call, and clients render them in a panel so you can attach an entity to a chat with one click.

URI	What it returns
`profile://EMAIL`	The full profile — consent, properties, timezone
`list://UUID`	List metadata plus up to 200 member previews
`list://name/NAME`	The same, looked up by list name
`segment://UUID`	Definition, evaluated count, and a sample
`template://UUID`	Subject, HTML, text, and MJML source if any
`campaign://UUID`	Campaign plus live stats

Prompts

prompts/list advertises server-provided playbooks; prompts/get renders the body with the caller’s arguments substituted in. Each names the tools to call and the order to call them, so picking a prompt is a one-shot way to trigger a multi-step workflow.

Name	Arguments
`draft_welcome_campaign`	`list_name` (required), `brand_voice`
`analyze_campaign`	`campaign_id` (required)
`propose_engagement_segment`	`kind` (required), `window_days`
`audit_suppressions`	—
`design_reengagement_flow`	—
`triage_inbox`	—

Last modified on August 29, 2026

Get started

Platform

Using the APIs

StateSet Response

StateSet ResponseCX

Temporal Engine

StateSet iCommerce Engine

StateSet iCommerce EDI Engine

StateSet Mail

StateSet iCommerce Voice Engine

StateSet iCommerce NSR Engine

AI Agents

StateSet Agents

StateSet iCommerce Sandbox Engine

StateSet ACP

StateSet UCP

StateSet ICP

StateSet Sequencer

StateSet Set L2

StateSet Cloud

Apps & Consoles

Tools

Mail MCP Server

Transports

stdio — recommended for desktop clients

HTTP — recommended for remote clients

Tools

Profiles, lists and segments

Templates and campaigns

Sending, flows and events

The agent inbox

Resources

Prompts

​Transports

​stdio — recommended for desktop clients

​HTTP — recommended for remote clients

​Tools

​Profiles, lists and segments

​Templates and campaigns

​Sending, flows and events

​The agent inbox

​Resources

​Prompts

​Related

Transports

stdio — recommended for desktop clients

HTTP — recommended for remote clients

Tools

Profiles, lists and segments

Templates and campaigns

Sending, flows and events

The agent inbox

Resources

Prompts

Related