> ## Documentation Index
> Fetch the complete documentation index at: /docs/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Tools Reference

> Detailed parameter specifications, usage examples, and natural language prompts for all 19 Mailofly MCP tools.

# MCP Tools Reference

The Mailofly MCP server exposes **19 purpose-built tools** allowing your AI assistant to perform actions in your Mailofly workspace. Every tool is strictly typed, validated via Zod schemas, and returns clean JSON payloads.

***

## 1. Transactional & Marketing Emails

### `mailofly_send_email`

Dispatch an individual transactional or marketing email with HTML/text content, attachments, CC/BCC, reply-to routing, and scheduled sending.

**Parameters:**

| Parameter | Type | Required | Description |
| :- | :- | :- | :- |
| `to` | `string \| string[]` | Yes | Primary recipient email or array of recipient emails. |
| `subject` | `string` | Yes | Subject line of the email. |
| `from` | `string` | No | Sender address (e.g. `"Acme <hello@yourdomain.com>"`). Defaults to workspace default identity. |
| `html` | `string` | No | Rich HTML content for the message body. |
| `text` | `string` | No | Plain-text fallback for the message body. |
| `cc` | `string \| string[]` | No | Carbon copy recipient(s). |
| `bcc` | `string \| string[]` | No | Blind carbon copy recipient(s). |
| `reply_to` | `string \| string[]` | No | Reply-to email address(es). |
| `scheduled_at` | `string` | No | Schedule delivery for a future time (ISO 8601 or natural phrasing like `"in 2 hours"`). |
| `tags` | `Array<{ name: string, value: string }>` | No | Key-value analytics tags attached to the message. |

> [accordion] Example Natural Language Prompt
>
> ```text theme={null}
> Send an email to user@example.com with the subject 'Welcome to our platform!' 
> and an HTML body welcoming them aboard, sent from 'Team <team@yourdomain.com>'.
> ```

***

### `mailofly_send_batch`

Send up to 100 distinct emails in a single request. Each email can have its own recipient, subject, and personalized body.

**Parameters:**

| Parameter | Type | Required | Description |
| :- | :- | :- | :- |
| `emails` | `Array<EmailPayload>` | Yes | Array of up to 100 email objects (each accepts `to`, `subject`, `html`, `text`, `cc`, `bcc`, `reply_to`, `scheduled_at`). |

> [accordion] Example Natural Language Prompt
>
> ```text theme={null}
> Send batch onboarding emails to the three users in our beta signup list:
> alice@example.com, bob@example.com, and charlie@example.com.
> ```

***

### `mailofly_get_email`

Inspect the live delivery status, bounce events, and metadata of a previously dispatched email.

**Parameters:**

| Parameter | Type | Required | Description |
| :- | :- | :- | :- |
| `email_id` | `string` | Yes | The unique identifier of the email (UUID). |

> [accordion] Example Natural Language Prompt
>
> ```text theme={null}
> Check the delivery status of email 4ef9a417-02e9-4d39-ad75-9611e0fcc33c. Was it delivered or did it bounce?
> ```

***

### `mailofly_list_emails`

Retrieve a paginated list of sent emails with delivery statuses and timestamps.

**Parameters:**

| Parameter | Type | Required | Description |
| :- | :- | :- | :- |
| `limit` | `number` | No | Number of records to return (1–100, default `50`). |
| `after` | `string` | No | Cursor to fetch records after this ID. |
| `before` | `string` | No | Cursor to fetch records before this ID. |

> [accordion] Example Natural Language Prompt
>
> ```text theme={null}
> Show me the 10 most recent emails sent from our account and their delivery statuses.
> ```

***

### `mailofly_cancel_email`

Cancel a scheduled email before its scheduled dispatch time.

**Parameters:**

| Parameter | Type | Required | Description |
| :- | :- | :- | :- |
| `email_id` | `string` | Yes | The ID of the scheduled email to cancel. |

> [accordion] Example Natural Language Prompt
>
> ```text theme={null}
> Cancel the announcement email scheduled for tomorrow with ID ae2014de-c168-4c61-8267-70d2662a1ce1.
> ```

***

## 2. Audience & Contacts

### `mailofly_list_contacts`

Query contacts in your audience, with optional filtering by segment.

**Parameters:**

| Parameter | Type | Required | Description |
| :- | :- | :- | :- |
| `segment_id` | `string` | No | Filter contacts belonging to a specific segment ID. |
| `limit` | `number` | No | Max number of contacts to retrieve (1–100). |

> [accordion] Example Natural Language Prompt
>
> ```text theme={null}
> List all contacts currently subscribed to our 'Product Updates' segment.
> ```

***

### `mailofly_create_contact`

Add a new subscriber or customer contact with optional custom attributes.

**Parameters:**

| Parameter | Type | Required | Description |
| :- | :- | :- | :- |
| `email` | `string` | Yes | Contact's email address. |
| `first_name` | `string` | No | Contact's first name. |
| `last_name` | `string` | No | Contact's last name. |
| `properties` | `Record<string, unknown>` | No | Custom attributes (e.g. `{ "tier": "enterprise", "country": "US" }`). |

> [accordion] Example Natural Language Prompt
>
> ```text theme={null}
> Add sarah.connor@example.com to our audience with first name Sarah and property role='Tech Lead'.
> ```

***

### `mailofly_get_contact`

Retrieve contact details, subscribed segments, and custom properties by ID.

**Parameters:**

| Parameter | Type | Required | Description |
| :- | :- | :- | :- |
| `contact_id` | `string` | Yes | The unique ID of the contact. |

> [accordion] Example Natural Language Prompt
>
> ```text theme={null}
> Find contact details for ID cnt_89ab34ef-1234.
> ```

***

### `mailofly_delete_contact`

Permanently remove a contact from your audience.

**Parameters:**

| Parameter | Type | Required | Description |
| :- | :- | :- | :- |
| `contact_id` | `string` | Yes | The unique ID of the contact to delete. |

> [accordion] Example Natural Language Prompt
>
> ```text theme={null}
> Remove the contact with ID cnt_89ab34ef-1234 from our database.
> ```

***

## 3. Email Templates

### `mailofly_list_templates`

List all reusable templates configured in your workspace.

**Parameters:** None required.

> [accordion] Example Natural Language Prompt
>
> ```text theme={null}
> What email templates do we have available in Mailofly?
> ```

***

### `mailofly_get_template`

Fetch a template's HTML body, plain text, and placeholder variable schema.

**Parameters:**

| Parameter | Type | Required | Description |
| :- | :- | :- | :- |
| `template_id` | `string` | Yes | The unique ID of the template. |

> [accordion] Example Natural Language Prompt
>
> ```text theme={null}
> Show me the HTML code and variables used in the 'Password Reset' template.
> ```

***

### `mailofly_create_template`

Create a reusable template. Use native document JSON for templates edited in Mailofly's visual editor; use `html`/`text` for legacy HTML templates.

**Parameters:**

| Parameter | Type | Required | Description |
| :- | :- | :- | :- |
| `name` | `string` | Yes | Name for the template. |
| `subject` | `string` | No | Default subject line. |
| `html` | `string` | No | HTML content with variable placeholders (e.g. `{{name}}`). |
| `text` | `string` | No | Plain-text fallback content. |
| `from_email` | `string` | No | Default From address for the template. |
| `reply_to` | `string` | No | Default Reply-To address. |
| `preview_text` | `string` | No | Inbox preview snippet. |
| `document` | `object` | No | Native Mailofly source (`kind: "mailofly-document"`, `schemaVersion: 1`). The API validates and compiles it; do not pass HTML in this field. |

When `document` is supplied, the template is saved as an unpublished draft. Call `mailofly_get_template_draft` to get `base_revision` and `draft_revision`, then `mailofly_publish_template` to publish it. Publishing requires a valid document and subject. Only published templates can be used by campaigns.

### `mailofly_get_template_draft`

Retrieve native source JSON and revision values for a template draft. Requires `template_id`.

### `mailofly_publish_template`

Publish a native template version for use in campaigns. Pass `template_id`, `base_revision`, and `draft_revision` from `mailofly_get_template_draft`.

> [accordion] Example Natural Language Prompt
>
> ```text theme={null}
> Create a new template called 'Order Receipt' with placeholders for {{customer_name}}, {{order_id}}, and {{total_amount}}.
> ```

***

## 4. Broadcast Campaigns

### `mailofly_list_campaigns`

List all marketing and broadcast campaigns in your account.

**Parameters:** None required.

> [accordion] Example Natural Language Prompt
>
> ```text theme={null}
> List our recent email campaigns and check their send statuses.
> ```

***

### `mailofly_create_campaign`

Create an unsent campaign draft or scheduled campaign targeted at an audience segment. Creating a campaign does not send it.

**Parameters:**

| Parameter | Type | Required | Description |
| :- | :- | :- | :- |
| `name` | `string` | Yes | Internal campaign title. |
| `title` | `string` | No | Internal campaign title (`name` is also accepted). |
| `subject` | `string` | No | Subject line for the broadcast. |
| `from` | `string` | No | Sender address or display name. |
| `html` | `string` | No | HTML message content. |
| `text` | `string` | No | Plain-text message content. |
| `segment_id` | `string` | No | Target segment ID. |
| `template_id` | `string` | No | ID of a published reusable template. |
| `schedule_type` | `string` | No | `manual` (default), `scheduled_once`, `recurring`, or `recurring_new_contacts`. |
| `scheduled_at` | `string` | No | ISO datetime for `scheduled_once`. |
| `recurrence_interval` | `integer` | No | Positive recurrence interval. |
| `recurrence_unit` | `string` | No | `day`, `week`, `month`, or `year`. |

Call `mailofly_send_campaign` only when sending is explicitly requested.

> [accordion] Example Natural Language Prompt
>
> ```text theme={null}
> Draft a new campaign called 'Spring Release' with the subject 'Introducing Mailofly 2.0' targeting the 'All Users' segment.
> ```

***

### `mailofly_send_campaign`

Trigger immediate or scheduled delivery of a campaign broadcast.

**Parameters:**

| Parameter | Type | Required | Description |
| :- | :- | :- | :- |
| `campaign_id` | `string` | Yes | The campaign ID to send. |
| `send_now` | `boolean` | No | Whether to dispatch immediately (defaults to `true`). |

> [accordion] Example Natural Language Prompt
>
> ```text theme={null}
> Launch the campaign with ID cmp_77a912bc now.
> ```

***

## 5. Domains & Deliverability

### `mailofly_list_domains`

Check all sending domains and their DNS record verification states (SPF, DKIM, DMARC, Return-Path).

**Parameters:** None required.

> [accordion] Example Natural Language Prompt
>
> ```text theme={null}
> List all our sending domains and verify if their DKIM and SPF records are active.
> ```

***

### `mailofly_verify_domain`

Trigger a real-time DNS check for a pending or active domain.

**Parameters:**

| Parameter | Type | Required | Description |
| :- | :- | :- | :- |
| `domain_id` | `string` | Yes | The domain ID to verify. |

> [accordion] Example Natural Language Prompt
>
> ```text theme={null}
> Trigger a DNS check for domain dom_4ef9a417 to see if our new TXT records have propagated.
> ```

***

### `mailofly_list_identities`

List configured sender identities and routing accounts.

**Parameters:** None required.

> [accordion] Example Natural Language Prompt
>
> ```text theme={null}
> Show all sender identities and default 'From' addresses configured in our account.
> ```

***

## 6. Usage & Metrics

### `mailofly_get_usage`

Retrieve email volume, delivery rates, bounce counters, and monthly quota limits.

**Parameters:**

| Parameter | Type | Required | Description |
| :- | :- | :- | :- |
| `days` | `number` | No | Number of days of historical metrics to analyze (1–90, default `30`). |

> [accordion] Example Natural Language Prompt
>
> ```text theme={null}
> How many emails have we sent in the last 14 days, and what is our bounce rate?
> ```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.