Complete reference for all 18 MisarMail MCP tools — inputs, required fields, and example responses.

MCP Tools Reference

All tools are exposed by the misar-mail MCP server. Authentication is handled automatically via MISARMAIL_API_KEY. All responses are JSON strings.

Send

`send_email`

Send a transactional email from a verified MisarMail email account.

Required: from, to, subject

Parameter	Type	Description
`from`	object	Sender — `email` (required), `name`
`to`	array	Recipients — each `{ email, name }`. 1–100 addresses
`cc`	array	CC recipients — each `{ email, name }`. Max 50
`bcc`	array	BCC recipients — each `{ email, name }`. Max 50
`reply_to`	object	Reply-to — `{ email, name }`
`subject`	string	Subject line (max 998 chars)
`html`	string	HTML body (max 500 KB)
`text`	string	Plain text body (max 500 KB)
`alias_id`	string	Route via a specific alias SMTP pool
`idempotency_key`	string	Prevent duplicate sends (max 128 chars)
`tags`	array	Tracking tags — max 10, each max 64 chars
`metadata`	object	Custom key-value pairs (max 20 pairs)

Example response:

{
  "id": "msg_01hx...",
  "status": "queued"
}

Campaigns

`list_campaigns`

List email campaigns with optional status filter and pagination.

Parameter	Type	Description
`page`	number	Page number (default: 1)
`limit`	number	Results per page, max 50 (default: 20)
`status`	string	`draft` \| `scheduled` \| `sending` \| `sent` \| `paused` \| `cancelled`

Example response:

{
  "data": [
    { "id": "cmp_01hx...", "name": "April Newsletter", "status": "sent", "sentAt": "2026-04-01T10:00:00Z" }
  ],
  "total": 1,
  "page": 1
}

`get_campaign`

Get a single campaign by ID.

Required: campaign_id

Parameter	Type	Description
`campaign_id`	string	Campaign UUID

Example response:

{
  "id": "cmp_01hx...",
  "name": "April Newsletter",
  "subject": "What's new in April",
  "status": "sent",
  "sentAt": "2026-04-01T10:00:00Z",
  "stats": { "sent": 1200, "opened": 420, "clicked": 88 }
}

`create_campaign`

Create a new email campaign.

Required: name, subject, fromName, fromEmail

Parameter	Type	Description
`name`	string	Campaign name (max 100 chars)
`subject`	string	Subject line (max 255 chars)
`fromName`	string	Sender display name
`fromEmail`	string	Sender email address
`replyTo`	string	Reply-to email address
`bodyHtml`	string	HTML email body (max 500 KB)
`bodyText`	string	Plain text email body
`templateId`	string	Template UUID to use
`segmentId`	string	Contact segment UUID to target
`scheduledAt`	string	ISO 8601 datetime to schedule send (must be in future)

Example response:

{
  "id": "cmp_01hx...",
  "status": "draft",
  "createdAt": "2026-05-15T09:00:00Z"
}

`send_campaign`

Immediately send a draft campaign to its target segment.

Required: campaign_id

Parameter	Type	Description
`campaign_id`	string	Campaign UUID to send

Example response:

{
  "id": "cmp_01hx...",
  "status": "sending"
}

Contacts

`list_contacts`

List contacts with optional status filter and search.

Parameter	Type	Description
`page`	number	Page number (default: 1)
`limit`	number	Results per page, max 100 (default: 20)
`status`	string	`subscribed` \| `unsubscribed` \| `bounced` \| `complained`
`search`	string	Search by email, first name, or last name

Example response:

{
  "data": [
    { "id": "con_01hx...", "email": "[email protected]", "status": "subscribed" }
  ],
  "total": 1
}

`create_contact`

Create a new contact.

Required: email

Parameter	Type	Description
`email`	string	Contact email address
`firstName`	string	First name
`lastName`	string	Last name
`status`	string	`subscribed` \| `unsubscribed` \| `bounced` \| `complained` (default: `subscribed`)
`source`	string	Source identifier (max 255 chars)
`tags`	array	Tags to assign (max 50)
`customFields`	object	Custom field key-value pairs (max 50 keys, 50 KB)

Example response:

{
  "id": "con_01hx...",
  "email": "[email protected]",
  "status": "subscribed"
}

`import_contacts`

Bulk import contacts from an array of contact objects.

Required: contacts

Parameter	Type	Description
`contacts`	array	Array of contact objects — each requires `email`; optionally `firstName`, `lastName`, `status`, `tags`

Example response:

{
  "imported": 150,
  "skipped": 3,
  "errors": []
}

Analytics

`get_analytics`

Get email analytics. Without campaign_id returns aggregate usage; with campaign_id returns per-campaign stats including open/click/bounce rates.

Parameter	Type	Description
`campaign_id`	string	Campaign UUID for per-campaign stats
`startDate`	string	Start date `YYYY-MM-DD` (default: 30 days ago)
`endDate`	string	End date `YYYY-MM-DD` (default: today)
`groupBy`	string	`day` \| `week` \| `month` (default: `day`)

Example response:

{
  "sent": 5000,
  "delivered": 4900,
  "opened": 1200,
  "clicked": 340,
  "bounced": 50,
  "openRate": 0.245,
  "clickRate": 0.069
}

Templates

`list_templates`

List email templates with optional type filter and pagination.

Parameter	Type	Description
`page`	number	Page number (default: 1)
`limit`	number	Results per page, max 50 (default: 20)
`type`	string	`marketing` \| `transactional` \| `automation`

Example response:

{
  "data": [
    { "id": "tpl_01hx...", "name": "Welcome Email", "type": "transactional" }
  ],
  "total": 1
}

`create_template`

Create a new email template. HTML is sanitized server-side.

Required: name, subject, bodyHtml

Parameter	Type	Description
`name`	string	Template name (max 100 chars)
`description`	string	Optional description (max 1000 chars)
`subject`	string	Subject line (max 255 chars)
`bodyHtml`	string	HTML email body (max 500 KB)
`bodyText`	string	Plain text fallback body (max 500 KB)
`templateType`	string	`marketing` \| `transactional` \| `automation` (default: `marketing`)
`variables`	array	Variable names used in the template (max 100)

Example response:

{
  "id": "tpl_01hx...",
  "name": "Welcome Email",
  "createdAt": "2026-05-15T09:00:00Z"
}

`render_template`

Render a template with variable substitutions. Returns final html, text, and subject.

Required: template_id

Parameter	Type	Description
`template_id`	string	Template UUID
`variables`	object	Key-value pairs to substitute in `{{variable}}` placeholders

Example response:

{
  "html": "<p>Hello, Alice!</p>",
  "text": "Hello, Alice!",
  "subject": "Welcome, Alice"
}

Validation

`validate_email`

Validate one or multiple email addresses. Checks syntax, MX records, SMTP reachability, and flags disposable/role/catch-all addresses. Deducts credits per verification.

Parameter	Type	Description
`email`	string	Single email address to validate (use this OR `emails`, not both)
`emails`	array	Batch of email addresses to validate (max 500)
`options.skip_smtp`	boolean	Skip SMTP verification (faster, less accurate)

Example response (single):

{
  "email": "[email protected]",
  "valid": true,
  "disposable": false,
  "role": false,
  "catchAll": false,
  "mxFound": true
}

Sandbox

`list_sandbox_sends`

List the most recent sends captured in sandbox mode. Sandbox sends do not deliver real email — use for testing. Returns up to 50 most recent entries.

No parameters required.

Example response:

{
  "data": [
    {
      "id": "sbx_01hx...",
      "to": [{ "email": "[email protected]" }],
      "subject": "Test email",
      "capturedAt": "2026-05-15T09:00:00Z"
    }
  ]
}

`clear_sandbox`

Clear all sandbox send records for the authenticated user.

No parameters required.

Example response:

{
  "deleted": 12
}

AI

`generate_subject_lines`

Generate AI-optimized email subject lines. Returns up to 10 suggestions with open-rate hints. Rate-limited to 10 requests/minute.

Required: topic

Parameter	Type	Description
`topic`	string	Campaign topic or content summary (5–500 chars)
`tone`	string	`professional` \| `casual` \| `urgent` \| `playful` \| `informative` (default: `professional`)
`audience`	string	Target audience description, e.g. `SaaS customers` (max 200 chars)
`count`	number	Number of subject lines to generate (1–10, default: 5)
`brand`	string	Brand name for context (max 100 chars)

Example response:

{
  "suggestions": [
    { "subject": "Your April recap is here", "openRateHint": "high" },
    { "subject": "Don't miss what's new in April", "openRateHint": "medium" }
  ]
}

A/B Testing

`list_ab_tests`

List A/B tests (campaign and subject line tests) with pagination.

Parameter	Type	Description
`page`	number	Page number (default: 1)
`limit`	number	Results per page, max 50 (default: 20)
`type`	string	`campaign` \| `subject`

Example response:

{
  "data": [
    { "id": "abt_01hx...", "campaign_id": "cmp_01hx...", "variant": "B", "type": "subject", "status": "running" }
  ],
  "total": 1
}

`create_ab_test`

Create a new A/B test variant for a campaign.

Required: campaign_id, variant

Parameter	Type	Description
`campaign_id`	string	Campaign UUID
`variant`	string	Variant label (1–5 chars), e.g. `B`
`test_type`	string	`content` \| `subject` \| `send_time` \| `from_name` \| `preheader` (default: `content`)
`subject`	string	Variant subject line (max 255 chars)
`preheader`	string	Variant preheader text (max 255 chars)
`body_html`	string	Variant HTML body (max 500 KB)
`from_name`	string	Variant sender name (max 100 chars)
`send_percent`	number	Percentage of audience for this variant (1–99, default: 50)
`auto_select_winner`	boolean	Automatically select winner after wait period
`winner_wait_hours`	number	Hours to wait before auto-selecting winner (1–168, default: 4)

Example response:

{
  "id": "abt_01hx...",
  "campaign_id": "cmp_01hx...",
  "variant": "B",
  "status": "draft"
}

`select_ab_test_winner`

Select the winning variant for a campaign A/B test. Copies winning content back onto the parent campaign.

Required: test_id, winner_variant

Parameter	Type	Description
`test_id`	string	A/B test UUID (`campaign_ab_tests.id`)
`winner_variant`	string	Variant label to declare winner
`metric`	string	`opens` \| `clicks` \| `revenue` \| `conversions` (default: `opens`)

Example response:

{
  "test_id": "abt_01hx...",
  "winner": "B",
  "metric": "opens",
  "appliedToCampaign": true
}

MCP Tools Reference

On this page