# MCP tool reference

> Every tool on the hosted Emailit MCP server, grouped by toolset, with its kind, required scope, role requirement and arguments.

The hosted server at `https://api.emailit.com/mcp` exposes 109 tools in 15 toolsets. This reference is generated from the server's tool catalog, so it always matches what your assistant sees. Tool and argument descriptions are shown as the server sends them, in English.

**Scope.** Tools with scope `sending` also work with `full`. See [Workspaces and permissions](/docs/mcp/workspaces-and-permissions/).

**Kind.** **Read** makes no changes. **Create** and **update** change data. **Action** changes state. **Delete** removes data. **Destructive** can't be undone. **External** calls a URL you own. **Send** reaches real recipients. Kinds map to MCP tool annotations (`readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`) so clients can ask before running write tools.

**Workspace.** With OAuth, every tool outside the Workspace toolset also takes an optional `workspace` argument (ID or exact name) to run that call in another allowed workspace. Tools marked **Admin role** are refused with `admin_role_required` for workspace Members. API key connections have no `workspace` argument and no role limits.

**Results.** Tools return JSON as text for every client and as `structuredContent` for clients that read structured results. List tools accept `page`, `limit` and structured filters (`{ field, condition, value }`).

### Workspace (`workspace`)

| Tool | Kind | Scope | Description |
| --- | --- | --- | --- |
| `get-current-workspace` | read | sending | Return the Emailit workspace this connection acts on by default, your role in it, and the granted scope. Call it to confirm which account changes apply to. |
| `list-workspaces` | read | sending | List the workspaces this connection may use, with your role in each. Pass a workspace ID or name as `workspace` to any tool to act in it. OAuth connections only. |
| `switch-workspace` | update | sending | Change the default workspace for later tool calls on this connection. To act in another workspace for a single call, pass `workspace` to that tool instead. OAuth connections only. Arguments: `workspace_id` (required). |
| `create-workspace` | create | full | Create a new workspace, give this connection access to it, and switch to it. OAuth connections only. Arguments: `name` (required). |

### Emails (`emails`)

| Tool | Kind | Scope | Description |
| --- | --- | --- | --- |
| `send-email` | send | sending | Send a transactional email from a verified sending domain. Supports HTML, plain text, templates with variables, attachments, CC/BCC, scheduling, and open/click tracking. Delivers to real recipients, so confirm recipients and content with the user first.  Arguments: `from`, `to` (required), `subject`, `html`, `text`, `reply_to`, `cc`, `bcc`, `template`, `variables`, `attachments`, `headers`, `meta`, `scheduled_at`, `tracking`. |
| `list-emails` | read | full | List sent and received emails with pagination, status, recipient, sender, subject, domain, API key, and date filters.  Arguments: `page`, `limit`, `search`, `filters`, `match`, `sort`, `order`, `type`, `status`, `rcpt_to`, `mail_from`, `subject`, `api_key_id`, `sending_domain_id`, `date_from`, `date_to`. |
| `get-email` | read | full | Retrieve a single email with its status and delivery details.  Arguments: `id` (required). |
| `get-email-raw` | read | full | Return the full raw MIME message of an email.  Arguments: `id` (required). |
| `get-email-body` | read | full | Return the parsed text and HTML body of an email.  Arguments: `id` (required). |
| `get-email-attachments` | read | full | Return the attachments of an email.  Arguments: `id` (required). |
| `get-email-meta` | read | full | Return email metadata and headers without attachment content.  Arguments: `id` (required). |
| `update-email` | update | sending | Change the send time of a scheduled email.  Arguments: `id` (required), `scheduled_at` (required). |
| `cancel-email` | destructive | sending | Best-effort cancel of a scheduled, accepted, or attempted email. Pulls it from the send queue; not guaranteed if delivery already started.  Arguments: `id` (required). |
| `retry-email` | send | sending | Retry delivery of a failed, errored, or held email to its original recipients.  Arguments: `id` (required). |
| `forward-email` | send | sending | Forward an outgoing email to a new recipient. Default is a plain resend. Set include_headers to add forwarded headers and an optional comment. Limited to 3 forwards per hour per workspace.  Arguments: `id` (required), `to` (required), `include_headers`, `comment`, `body`, `html`, `text`, `from`, `subject`. |

### Domains (`domains`)

| Tool | Kind | Scope | Description |
| --- | --- | --- | --- |
| `create-domain` | create | full | Add a sending domain. Returns the SPF, DKIM, return-path, and DMARC DNS records to publish before verifying.  Arguments: `name` (required), `outgoing`, `incoming`, `use_for_any`, `track_loads`, `track_clicks`, `dmarc_reports`. |
| `get-domain` | read | full | Retrieve a domain with its DNS records and per-record verification status.  Arguments: `id` (required). |
| `list-domains` | read | full | List sending domains in the workspace.  Arguments: `page`, `limit`, `search`, `filters`, `match`, `sort`, `order`. |
| `update-domain` | update | full | Update domain settings such as open/click tracking, inbound, or DMARC report collection.  Arguments: `id` (required), `outgoing`, `incoming`, `use_for_any`, `track_loads`, `track_clicks`, `dmarc_reports`, `tracking_key`, `inbound_key`. |
| `delete-domain` | delete | full | Permanently delete a domain. Sending from it stops immediately. Requires the Admin role. Arguments: `id` (required). |
| `verify-domain` | action | full | Run a DNS check now and update the verification status of each record.  Arguments: `id` (required). |

### DMARC (`dmarc`)

| Tool | Kind | Scope | Description |
| --- | --- | --- | --- |
| `list-dmarc-reports` | read | full | List DMARC aggregate or forensic reports received for a domain.  Arguments: `id` (required), `page`, `limit`, `filters`, `match`, `type`, `status`, `org_name`, `from`, `to`, `offset`. |
| `get-dmarc-report` | read | full | Retrieve one DMARC aggregate report with its records.  Arguments: `id` (required), `report_id` (required). |
| `list-dmarc-forensic-reports` | read | full | List DMARC forensic (failure) reports for a domain.  Arguments: `id` (required), `from`, `to`, `limit`, `offset`. |
| `get-dmarc-forensic-report` | read | full | Retrieve one DMARC forensic report.  Arguments: `id` (required), `report_id` (required). |
| `get-dmarc-stats` | read | full | DMARC pass/fail totals and alignment rates for a domain over a date range.  Arguments: `id` (required), `from`, `to`. |
| `list-dmarc-sources` | read | full | Sending sources (IPs and hostnames) seen in DMARC reports, with pass/fail counts.  Arguments: `id` (required), `from`, `to`. |
| `list-dmarc-countries` | read | full | DMARC message volume by sending country.  Arguments: `id` (required), `from`, `to`. |
| `list-dmarc-asns` | read | full | DMARC message volume by sending network (ASN).  Arguments: `id` (required), `from`, `to`. |
| `list-dmarc-reporters` | read | full | Organizations that sent DMARC reports for the domain.  Arguments: `id` (required), `from`, `to`. |
| `upload-dmarc-report` | create | full | Import a DMARC aggregate report (XML, or base64 of a .xml/.gz/.zip file) for a domain.  Arguments: `id` (required), `content`, `content_base64`, `filename`. |

### Templates (`templates`)

| Tool | Kind | Scope | Description |
| --- | --- | --- | --- |
| `create-template` | create | full | Create an email template. Reference it from send-email by ID or alias; publish it before use.  Arguments: `name` (required), `alias` (required), `from`, `subject`, `reply_to`, `html`, `text`, `editor`. |
| `get-template` | read | full | Retrieve a template with its content.  Arguments: `id` (required). |
| `list-templates` | read | full | List templates in the workspace.  Arguments: `page`, `limit`, `filters`, `match`, `sort`, `order`, `include_content`. |
| `update-template` | update | full | Update a template draft. Publish it to make the change live.  Arguments: `id` (required), `name`, `alias`, `from`, `subject`, `reply_to`, `html`, `text`, `editor`. |
| `delete-template` | delete | full | Permanently delete a template.  Arguments: `id` (required). |
| `publish-template` | action | full | Publish the current template draft so new sends use it.  Arguments: `id` (required). |

### API keys (`api_keys`)

| Tool | Kind | Scope | Description |
| --- | --- | --- | --- |
| `create-api-key` | create | full | Create an API key. The secret is returned only once; tell the user to store it securely. Requires the Admin role. Arguments: `name` (required), `scope`, `sending_domain_id`. |
| `get-api-key` | read | full | Retrieve an API key (without its secret).  Arguments: `id` (required). |
| `list-api-keys` | read | full | List API keys in the workspace.  Arguments: `page`, `limit`, `search`, `filters`, `match`, `sort`, `order`. |
| `update-api-key` | update | full | Rename an API key. Requires the Admin role. Arguments: `id` (required), `name` (required). |
| `delete-api-key` | delete | full | Permanently revoke an API key. Apps using it stop working immediately. Requires the Admin role. Arguments: `id` (required). |
| `regenerate-api-key` | destructive | full | Issue a new secret for an API key and invalidate the old one immediately. The new secret is returned only once. Requires the Admin role. Arguments: `id` (required). |

### Audiences and subscribers (`audiences`)

| Tool | Kind | Scope | Description |
| --- | --- | --- | --- |
| `create-audience` | create | full | Create an audience (mailing list) for campaigns and automations.  Arguments: `name` (required). |
| `get-audience` | read | full | Retrieve an audience with subscriber counts.  Arguments: `id` (required). |
| `list-audiences` | read | full | List audiences in the workspace.  Arguments: `page`, `limit`, `search`, `filters`, `match`, `sort`, `order`. |
| `update-audience` | update | full | Rename an audience.  Arguments: `id` (required), `name` (required). |
| `delete-audience` | delete | full | Permanently delete an audience and its subscriber records. Contacts are kept.  Arguments: `id` (required). |
| `list-audience-subscribers` | read | full | List subscribers of an audience, optionally only subscribed or unsubscribed.  Arguments: `id` (required), `page`, `limit`, `search`, `filters`, `match`, `sort`, `order`, `subscribed`. |
| `get-audience-subscriber` | read | full | Retrieve one subscriber of an audience.  Arguments: `id` (required), `subscriber_id` (required). |
| `add-audience-subscriber` | create | full | Add an email address to an audience. Creates the contact if it does not exist.  Arguments: `id` (required), `email` (required), `first_name`, `last_name`, `custom_fields`. |
| `update-audience-subscriber` | update | full | Update a subscriber, including subscribing or unsubscribing them from the audience.  Arguments: `id` (required), `subscriber_id` (required), `email`, `first_name`, `last_name`, `custom_fields`, `subscribed`. |
| `remove-audience-subscriber` | delete | full | Remove a subscriber from an audience. The contact is kept.  Arguments: `id` (required), `subscriber_id` (required). |

### Contacts (`contacts`)

| Tool | Kind | Scope | Description |
| --- | --- | --- | --- |
| `create-contact` | create | full | Create a contact, optionally subscribing it to audiences and setting custom fields.  Arguments: `email` (required), `first_name`, `last_name`, `custom_fields`, `audiences`, `unsubscribed`. |
| `get-contact` | read | full | Retrieve a contact by ID or email address.  Arguments: `id` (required). |
| `list-contacts` | read | full | List contacts with search, audience, subscription, and custom-field filters.  Arguments: `page`, `limit`, `search`, `filters`, `match`, `sort`, `order`, `audience_id`, `unsubscribed`. |
| `update-contact` | update | full | Update a contact. Passing audiences replaces its audience memberships.  Arguments: `id` (required), `email`, `first_name`, `last_name`, `custom_fields`, `audiences`, `unsubscribed`. |
| `delete-contact` | delete | full | Permanently delete a contact and its audience memberships.  Arguments: `id` (required). |
| `bulk-update-contacts` | destructive | full | Apply one action to up to 100 contacts: delete, add_to_audience, remove_from_audience, unsubscribe, or resubscribe.  Arguments: `action` (required), `ids` (required), `audience_id`. |
| `export-contacts` | read | full | Export contacts matching the filters as CSV text (email, names, subscription, audiences, custom fields).  Arguments: `page`, `limit`, `search`, `filters`, `match`, `sort`, `order`, `audience_id`, `unsubscribed`. |

### Suppressions (`suppressions`)

| Tool | Kind | Scope | Description |
| --- | --- | --- | --- |
| `create-suppression` | create | full | Add an email address to the suppression list so Emailit never sends to it.  Arguments: `email` (required), `type`, `reason`, `keep_until`. |
| `get-suppression` | read | full | Retrieve a suppression by ID or email address.  Arguments: `id` (required). |
| `list-suppressions` | read | full | List suppressed addresses with search, type, reason, and expiry filters.  Arguments: `page`, `limit`, `search`, `filters`, `match`, `sort`, `order`. |
| `update-suppression` | update | full | Change the type, reason, or expiry of a suppression.  Arguments: `id` (required), `type`, `reason`, `keep_until`. |
| `delete-suppression` | delete | full | Remove an address from the suppression list so it can receive email again.  Arguments: `id` (required). |

### Webhooks (`webhooks`)

| Tool | Kind | Scope | Description |
| --- | --- | --- | --- |
| `create-webhook` | create | full | Create a webhook endpoint for email, domain, contact, and campaign events. The response includes the signing secret.  Arguments: `name` (required), `url` (required), `all_events`, `enabled`, `events`, `filter`. |
| `get-webhook` | read | full | Retrieve a webhook with its subscribed events and filter.  Arguments: `id` (required). |
| `list-webhooks` | read | full | List webhooks in the workspace.  Arguments: `page`, `limit`, `search`, `filters`, `match`, `sort`, `order`. |
| `update-webhook` | update | full | Update a webhook URL, name, events, filter, or enable it again.  Arguments: `id` (required), `name`, `url`, `all_events`, `enabled`, `events`, `filter`. |
| `delete-webhook` | delete | full | Permanently delete a webhook. Pending deliveries are dropped.  Arguments: `id` (required). |
| `test-webhook` | external | full | Send a sample event of the given type to the webhook URL and return the response. Limited to 5 per minute.  Arguments: `id` (required), `type` (required). |
| `reset-webhook-secret` | destructive | full | Rotate the webhook signing secret. The old secret stops working immediately; the new one is returned once.  Arguments: `id` (required). |
| `retry-failed-webhook-requests` | action | full | Queue every failed delivery of a webhook for retry and re-enable the webhook.  Arguments: `id` (required). |
| `retry-webhook-request` | action | full | Queue one webhook delivery for retry.  Arguments: `id` (required), `request_id` (required). |

### Campaigns (`campaigns`)

| Tool | Kind | Scope | Description |
| --- | --- | --- | --- |
| `list-campaigns` | read | full | List marketing campaigns, optionally by status.  Arguments: `page`, `limit`, `search`, `status`. |
| `get-campaign` | read | full | Retrieve a campaign with its content, recipients, and stats.  Arguments: `id` (required). |
| `create-campaign` | create | full | Create a draft campaign. Add recipients with update-campaign, then send with send-campaign.  Arguments: `name` (required), `subject`, `from_email`, `from_name`, `reply_to`, `preview_text`, `content`, `content_type`. |
| `update-campaign` | update | full | Update a draft campaign. Passing recipients replaces the audience list; at least one audience must be included.  Arguments: `id` (required), `name`, `subject`, `from_email`, `from_name`, `reply_to`, `preview_text`, `content`, `content_type`, `recipients`. |
| `delete-campaign` | delete | full | Permanently delete a campaign that has not been sent.  Arguments: `id` (required). |
| `send-campaign` | send | full | Send a campaign to its audiences now, or schedule it with scheduled_at. Delivers to real subscribers, so confirm with the user first.  Arguments: `id` (required), `scheduled_at`. |
| `cancel-campaign` | destructive | full | Cancel a draft or sending campaign. Scheduled campaigns cannot be canceled; delete them to stop the send. Emails already delivered are not recalled.  Arguments: `id` (required). |

### Automations (`automations`)

| Tool | Kind | Scope | Description |
| --- | --- | --- | --- |
| `list-automations` | read | full | List automations with context, status, and name filters.  Arguments: `page`, `per_page`, `context`, `status`, `name`, `sort`, `order`. |
| `get-automation` | read | full | Retrieve an automation with its steps and connections.  Arguments: `id` (required). |
| `create-automation` | create | full | Create a draft automation from a trigger step, action steps, and connections between step keys. Start it with start-automation.  Arguments: `context` (required), `name` (required), `description`, `settings`, `steps` (required), `connections` (required). |
| `update-automation` | update | full | Update an automation. Passing steps or connections replaces the whole graph.  Arguments: `id` (required), `name`, `description`, `settings`, `steps`, `connections`. |
| `delete-automation` | delete | full | Delete an automation and stop any runs in progress.  Arguments: `id` (required). |
| `start-automation` | action | full | Start or resume an automation so new triggers enroll contacts.  Arguments: `id` (required). |
| `pause-automation` | action | full | Pause an automation. Runs in progress wait until it is started again.  Arguments: `id` (required). |
| `stop-automation` | action | full | Stop an automation and cancel runs in progress.  Arguments: `id` (required). |
| `trigger-automation` | send | full | Manually trigger a running automation with an optional payload. Its steps may send real emails.  Arguments: `id` (required), `payload`. |
| `list-automation-runs` | read | full | List runs of an automation, optionally by status.  Arguments: `id` (required), `page`, `per_page`, `status`. |
| `get-automation-run` | read | full | Retrieve one automation run with its step history.  Arguments: `id` (required), `run_id` (required). |
| `get-automation-stats` | read | full | Return run totals by status and outcome for an automation.  Arguments: `id` (required), `since`, `until`. |
| `get-automation-step-stats` | read | full | Return totals for one step, including the delivery funnel for send_email steps.  Arguments: `id` (required), `step_key` (required), `since`, `until`. |

### Forms (`forms`)

| Tool | Kind | Scope | Description |
| --- | --- | --- | --- |
| `list-forms` | read | full | List signup forms with name, type, and status filters.  Arguments: `page`, `limit`, `search`, `filters`, `match`, `sort`, `order`. |
| `get-form` | read | full | Retrieve a signup form with its definition and settings.  Arguments: `id` (required). |
| `create-form` | create | full | Create a draft signup form (popup, full page, flyout, embed, or banner).  Arguments: `name` (required), `type`, `definition`, `settings`. |
| `update-form` | update | full | Update a form name, type, definition, or settings.  Arguments: `id` (required), `name`, `type`, `definition`, `settings`. |
| `delete-form` | delete | full | Permanently delete a form. Embedded copies stop working.  Arguments: `id` (required). |
| `publish-form` | action | full | Publish a form so it starts collecting signups.  Arguments: `id` (required). |
| `unpublish-form` | action | full | Take a form offline. It stops collecting signups.  Arguments: `id` (required). |
| `reset-form-token` | destructive | full | Rotate the public form token. Existing embed codes stop working until updated.  Arguments: `id` (required). |

### Email verification (`verification`)

| Tool | Kind | Scope | Description |
| --- | --- | --- | --- |
| `verify-email` | create | full | Check whether one address is deliverable (syntax, MX, disposable, role, and optional SMTP checks). Uses verification credits.  Arguments: `email` (required), `mode`. |
| `create-verification-list` | create | full | Verify up to 10,000 addresses in the background. Uses one verification credit per address; poll get-verification-list for progress.  Arguments: `name` (required), `emails` (required). |
| `list-verification-lists` | read | full | List bulk verification lists with their progress.  Arguments: `page`, `limit`, `status`, `search`. |
| `get-verification-list` | read | full | Retrieve a verification list with progress and result counts.  Arguments: `id` (required). |
| `get-verification-list-results` | read | full | Return per-address results of a verification list, optionally by status or result.  Arguments: `id` (required), `page`, `limit`, `status`, `result`. |

### Events (`events`)

| Tool | Kind | Scope | Description |
| --- | --- | --- | --- |
| `list-events` | read | full | List workspace events (email delivered, bounced, clicked, contact created, and more), newest first.  Arguments: `page`, `limit`, `type`, `include_data`. |
| `get-event` | read | full | Retrieve one event with its full payload.  Arguments: `id` (required). |

---
Source: https://emailit.com/docs/mcp/tools/