MCP Integration¶

Connect MailJawn to AI assistants like Claude Desktop using the Model Context Protocol (MCP). Your AI agent gets direct access to subscribers, drafts, analytics, automations, and more — all through natural language.

What is MCP?¶

The Model Context Protocol is an open standard that lets AI assistants interact with external services through structured tools. Instead of copying data back and forth, your AI assistant calls MailJawn tools directly.

Connection Modes¶

MailJawn supports two MCP transport modes:

Mode	Best For	Transport
Streamable HTTP	Production, remote access, Claude Desktop	HTTPS with Bearer auth
Stdio	Local development, testing	Subprocess communication

Streamable HTTP (Production)¶

Add MailJawn to your Claude Desktop configuration (or any MCP-compatible client):

{
  "mcpServers": {
    "mailjawn": {
      "type": "http",
      "url": "https://api.mailjawn.com/mcp/",
      "headers": {
        "Authorization": "Bearer mj_your_api_key_here"
      }
    }
  }
}

For local development against a local MailJawn instance:

{
  "mcpServers": {
    "mailjawn-dev": {
      "type": "http",
      "url": "http://localhost:8000/mcp/",
      "headers": {
        "Authorization": "Bearer mj_your_api_key_here"
      }
    }
  }
}

Stdio (Local Development)¶

For direct subprocess communication:

{
  "mcpServers": {
    "mailjawn-dev": {
      "type": "stdio",
      "command": "python",
      "args": ["-m", "mailjawn.mcp.server"],
      "env": {
        "MAILJAWN_API_KEY": "mj_your_api_key_here"
      }
    }
  }
}

Tip

Use an API key with the MCP scope bundle. It includes the right mix of read/write permissions for AI agent workflows. See Account > API Keys.

Rate Limits¶

MCP requests are rate-limited to 60 requests per 60 seconds per API key. This is separate from the REST API rate limits.

Tool Reference¶

MailJawn exposes 50 MCP tools organized by category. Each tool has annotations that tell the AI assistant what kind of operation it performs.

Tool Annotations¶

Annotation	Meaning
`readOnlyHint`	Tool only reads data, never modifies anything
`destructiveHint`	Tool deletes or irreversibly changes data
`idempotentHint`	Safe to call multiple times with the same result
`openWorldHint`	Tool sends email or interacts with external services

AI assistants use these annotations to decide when to ask for confirmation. Destructive and email-sending tools typically require explicit approval.

Subscribers¶

Tool	Annotation	Description
`subscribers_list`	Read-only	List subscribers with filtering by status, tag, or search term
`subscribers_count`	Read-only	Fast count with optional breakdown by status
`stats_summary`	Read-only	Account-wide overview of all projects and subscriber metrics

Drafts¶

Tool	Annotation	Description
`drafts_list`	Read-only	List drafts, optionally filtered by status (`draft`, `scheduled`, `sent`)
`drafts_get`	Read-only	Get full draft including MJML source and compiled HTML
`drafts_preview`	Read-only	Test MJML compilation without saving
`drafts_create`	Additive	Create a draft with subject and MJML source
`drafts_update`	Additive	Update draft subject, MJML, or name
`drafts_delete`	Destructive	Delete a draft (sent drafts cannot be deleted)

Template variables available in MJML source:

{{subscriber.name}}, {{subscriber.email}}
{{subscriber.custom_fields.<key>}}
{{unsubscribe_url}}, {{address}}, {{company_name}}

Email Sending¶

Tool	Annotation	Description
`email_send_test`	Sends email	Send a test email to the account owner to verify SES integration
`drafts_send_preview`	Sends email	Send a draft to the account owner with `[Preview]` subject prefix
`drafts_send`	Sends email	Send a draft to subscribers immediately

drafts_send targeting options:

target="all" — all active subscribers
target="tag" with tag_slug — subscribers with a specific tag
target="ids" with subscriber_ids — specific subscriber UUIDs
segment_id — subscribers matching a saved segment

Scheduling¶

Tool	Annotation	Description
`drafts_schedule`	Sends email	Schedule a draft for future delivery
`drafts_cancel_schedule`	Idempotent	Cancel a scheduled send, revert to draft status
`drafts_schedule_preview`	Read-only	Preview timezone distribution before scheduling

Timezone strategies for drafts_schedule:

timezone_strategy="fixed" — everyone receives at the same moment
timezone_strategy="recipient" — each subscriber receives at their local time

Analytics¶

Tool	Annotation	Description
`campaigns_stats`	Read-only	Performance metrics for a sent campaign (opens, clicks, unsubscribes, link breakdown)
`campaigns_performance_summary`	Read-only	Cross-campaign aggregate analysis with top/worst performers and subject line patterns

Assets¶

Tool	Annotation	Description
`assets_list`	Read-only	Browse the organization's asset library with search
`assets_get`	Read-only	Get full asset details including dimensions and file size

Automations¶

Tool	Annotation	Description
`automations_list`	Read-only	List automations with enrollment stats
`automations_get`	Read-only	Get full automation details including node structure
`automations_create_series`	Additive	Create a multi-step welcome series automation
`automations_add_step`	Additive	Append a step to an existing automation
`automations_activate`	Idempotent	Enable an automation to process triggers
`automations_deactivate`	Destructive	Pause an automation (cancels pending enrollments)
`automations_remove_step`	Destructive	Delete a step from an automation

Content Calendar¶

Tool	Annotation	Description
`calendar_list`	Read-only	List calendar entries with status and date filtering
`calendar_get`	Read-only	Get a single calendar entry
`calendar_create`	Additive	Create a calendar entry
`calendar_bulk_create`	Additive	Create up to 50 entries atomically
`calendar_update`	Additive	Update calendar entry fields and status
`calendar_delete`	Destructive	Remove a calendar entry

Calendar statuses: planned → content_ready → draft_created → scheduled → sent (or skipped from any non-terminal status)

Segments¶

Tool	Annotation	Description
`segments_list`	Read-only	List saved subscriber segments
`segments_get`	Read-only	Get segment details including rules and subscriber count
`segments_create`	Additive	Create a segment with rule-based filtering
`segments_update`	Additive	Update segment rules or properties
`segments_preview`	Read-only	Test segment rules without saving (returns count + sample)
`segments_delete`	Destructive	Delete a segment

Segment rule types:

tag — filter by tag (has / not_has)
custom_field — filter by custom field value (eq, etc.)
date — filter by date field (gte, lte, relative like "-30d")
email — filter by email pattern (contains, domain_is, etc.)

Projects¶

Tool	Annotation	Description
`project_get_context`	Read-only	Get project strategy settings (audience, tone, cadence)
`project_update_context`	Additive	Update project strategy settings

Workflows¶

Tool	Annotation	Description
`define_email_strategy`	Read-only	Assess project readiness and get strategy guidance
`plan_content_calendar`	Read-only	Get calendar planning guidance with existing entries

Onboarding¶

Tool	Annotation	Description
`getting_started`	Read-only	Guided overview of MCP capabilities and quick-start steps

Resources¶

MCP resources provide static content that AI assistants can reference.

Resource URI	Description
`template://sample/email`	A sample MJML email template with CAN-SPAM footer and personalization variables

Example Workflow¶

Here's a typical conversation with an AI assistant connected to MailJawn:

You: "Create a welcome email for new subscribers and send me a preview."

Assistant: (calls drafts_create with MJML, then drafts_send_preview)

"I've created a welcome email draft and sent you a preview at joe@example.com. Check your inbox and let me know if you'd like any changes."

You: "Looks good — schedule it as a welcome series for new signups."

Assistant: (calls automations_create_series with the draft)

"Done. I've created a welcome automation that sends this email 1 hour after someone subscribes. It's inactive — want me to activate it?"

See also: Account > API Keys | REST API | Automations