MCP Server

Lumail's Model Context Protocol (MCP) server lets an AI assistant read and manage organization-scoped subscribers, campaigns, Workflows, tags, segments, settings, and analytics.

The tool catalog is generated from the same definitions used by Lumail's in-app agent, CLI, SDK, and Tools API. Use MCP tool discovery as the source of truth instead of relying on a fixed tool count.

Choose an endpoint

The OAuth endpoint cannot send, publish, schedule, delete, archive, or unsubscribe. Follow the ChatGPT and Codex guide for that setup.

The API-token endpoint is intended for trusted clients that need the wider catalog. Every request remains scoped to the organization that owns the token.

Connect with an API token

Create a token from Settings → API Tokens, then add the Streamable HTTP endpoint to your client:

{
  "mcpServers": {
    "lumail": {
      "url": "https://lumail.io/api/mcp/sse",
      "headers": {
        "Authorization": "Bearer lum_your_api_token_here"
      }
    }
  }
}

For a stdio-only client, use an HTTP bridge:

{
  "mcpServers": {
    "lumail": {
      "command": "pnpm",
      "args": [
        "dlx",
        "mcp-remote",
        "https://lumail.io/api/mcp/sse",
        "--header",
        "Authorization: Bearer lum_your_api_token_here"
      ]
    }
  }
}

Restart the MCP client after changing its configuration.

Discover resources

After authentication, the server advertises the MCP resources capability. Use resources/list and resources/read to retrieve:

• Lumail developer and agent start (https://lumail.io/, text/markdown) - concise product capabilities and canonical MCP, REST, SDK, CLI, support, and documentation links
• Lumail OpenAPI 3.1 specification (https://lumail.io/openapi.json, application/json) - typed REST operations, bearer authentication, request schemas, response schemas, and structured errors

Every returned URI also resolves over ordinary HTTPS. Resource content is public developer documentation; organization data remains available only through authenticated tools.

Discover tools dynamically

MCP clients receive the current tool names, descriptions, input schemas, and safety annotations during discovery. The same catalog is available over REST:

curl https://lumail.io/api/v2/tools \
  -H "Authorization: Bearer lum_your_api_token_here"

The v2 in /api/v2/tools is the Tools API version. Workflow tool names are canonical and unversioned.

Canonical Workflow tools

Lumail has one supported graph-based Workflow engine. Its MCP tools operate on editable drafts, immutable published versions, subscriber runs, goals, exits, and mutual-exclusion groups.

There are no version-suffixed Workflow tools and no step-by-step mutation tools. A Workflow draft is configured as one complete { steps, edges } graph.

Safe draft flow

1. Call get_skill with { "type": "workflow" }.
2. Use list_workflows or create_workflow to identify the target.
3. Call get_workflow immediately before editing and keep its exact updatedAt.
4. Resolve referenced tags, senders, snippets, campaigns, fields, goals, and groups with read tools.
5. Call configure_workflow_draft once with the complete steps and edges plus expectedUpdatedAt.
6. Read the Workflow back, inspect every configured internal email with get_campaign, and verify each render with render_campaign.

configure_workflow_draft creates or updates the internal WORKFLOW campaign owned by each EMAIL step. Do not call create_campaign for Workflow emails and do not attach broadcast campaigns directly.

Draft configuration never publishes or sends. Publishing and activation are separate, confirmation-gated actions.

Tool categories

The full catalog also includes tools for:

• Subscribers, composed filters, tags, and custom fields
• Campaign drafting, rendering, history, scheduling, and analytics
• Segments and organization analytics
• Email senders, domains, deliverability, and suppression management
• Snippets, variables, images, imports, and exports
• Transactional email and web content retrieval

Use get_skill before specialized operations such as Workflow graph configuration or email copywriting. Pass { "type": "docs" } to list every product docs page, then { "type": "docs", "page": "<slug>" } to read one. Use the schema returned by discovery rather than guessing parameter names.

Confirmation gates

High-impact tools use a two-call confirmation flow. The first call returns CONFIRMATION_REQUIRED with a five-digit confirmationCode. Show the proposed action to the user, then repeat the exact same tool call with that code within five minutes.

Confirmation-gated actions include sending or scheduling email, publishing or activating a Workflow, destructive deletion, archiving, and unsubscribe operations. The tool's annotations and first response are authoritative for the current catalog.

Codes are single-use, expire after five minutes, and are bound to the organization, tool, and exact input.

Operating rules

• Read the current resource immediately before changing it.
• Create campaigns and Workflows as drafts first.
• Never send, publish, activate, schedule, archive, unsubscribe, or delete without explicit user intent.
• Preserve updatedAt values for optimistic-concurrency operations.
• Use edit_campaign for campaign changes and configure_workflow_draft for complete Workflow graphs.
• Read back every mutation before reporting success.
• Keep API tokens secret and out of browser-side code, logs, and prompts.
• Respect organization rate limits and retry 429 responses with backoff.

Example prompts

Create a welcome Workflow draft with three emails over seven days.
Keep it unpublished, then show me the rendered text and links for every email.

List my paused Workflows and explain which published version each one uses.
Do not activate anything.

Add the subscriber [email protected] to the active onboarding Workflow.
Show me the exact action before requesting confirmation.

Troubleshooting

Tools do not appear: restart the MCP client, verify the endpoint, and confirm that the token belongs to the intended organization.

Unauthorized: create a new organization API token or reconnect the OAuth integration.

Workflow changed since it was read: call get_workflow again, merge intentionally, and retry with the new updatedAt.

Confirmation required: repeat the same call with the returned code. Changing another input creates a different confirmation challenge.

Related

• Workflow guide
• Tools API
• Tools API reference
• Claude MCP setup
• Cursor MCP setup
• API tokens