MCP

Overview

Mailisk supports the Model Context Protocol (MCP), allowing coding agents and automation tools to generate test email addresses, inspect inbound email and SMS workflows, and send outbound email through Mailisk.

The hosted MCP endpoint is:

https://api.mailisk.com/mcp

Setup

Requirements

To use Mailisk through MCP you need:

• A Mailisk organisation
• Organisation owner or admin access
• An MCP API key created in the Mailisk dashboard

MCP is available on every Mailisk plan. MCP API keys are separate from regular Mailisk REST API keys. They start with sk_mcp_ and can be scoped to specific MCP capabilities.

Create an MCP API key

1. Open MCP in the dashboard.
2. Choose the organisation you want the agent to access.
3. Click Create MCP key.
4. Choose the scopes the key should have.
5. Copy the generated secret immediately. It is only shown once.

The available scopes are:

• namespace:read: access namespace metadata used by email tools
• email:read: search, wait for, and fetch inbound emails
• email:send: send, reply to, forward, and inspect delivery status for outbound emails
• sms:read: list Mailisk SMS numbers, search SMS history, and wait for inbound SMS messages

Inbound email workflows normally need both namespace:read and email:read. New outbound sends and delivery-status inspection need email:send; replies and forwards additionally need email:read because they load a source inbound email. SMS tools need sms:read; they do not require the email scopes. Sending email and reading SMS are opt-in capabilities.

Generic MCP configuration

Most clients that support remote Streamable HTTP servers accept this JSON configuration shape:

{
  "mcpServers": {
    "mailisk": {
      "url": "https://api.mailisk.com/mcp",
      "headers": {
        "Authorization": "Bearer sk_mcp_YOUR_API_KEY"
      }
    }
  }
}

Replace sk_mcp_YOUR_API_KEY with the MCP API key secret from the dashboard. Some clients use serverUrl instead of url; check the client-specific guides below when needed.

Codex

Add Mailisk to ~/.codex/config.toml:

[mcp_servers.mailisk]
enabled = true
url = "https://api.mailisk.com/mcp"

[mcp_servers.mailisk.http_headers]
Authorization = "Bearer sk_mcp_YOUR_API_KEY"

Replace sk_mcp_YOUR_API_KEY with the MCP API key secret from the dashboard, then restart Codex. The same configuration is used by the Codex CLI and IDE extension on that host.

Claude Code

Run this command from the project where you want Mailisk to be available:

claude mcp add --transport http mailisk https://api.mailisk.com/mcp \
  --header "Authorization: Bearer sk_mcp_YOUR_API_KEY"

Replace the placeholder with your MCP API key. Run claude mcp get mailisk or use /mcp inside Claude Code to check the connection.

Cursor

Add Mailisk to .cursor/mcp.json for the current project or ~/.cursor/mcp.json for all projects:

{
  "mcpServers": {
    "mailisk": {
      "url": "https://api.mailisk.com/mcp",
      "headers": {
        "Authorization": "Bearer sk_mcp_YOUR_API_KEY"
      }
    }
  }
}

Replace sk_mcp_YOUR_API_KEY with the MCP API key secret from the dashboard, then open Cursor Settings → MCP to confirm that the server is enabled.

Windsurf

Add Mailisk to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "mailisk": {
      "serverUrl": "https://api.mailisk.com/mcp",
      "headers": {
        "Authorization": "Bearer sk_mcp_YOUR_API_KEY"
      }
    }
  }
}

Replace the placeholder with your MCP API key, then refresh the MCP servers from the Windsurf MCP settings.

Core features

Your app or test triggers the email or SMS; Mailisk gives the agent isolated recipients, message inspection, and bounded waits to verify the result.

Test new-user email flows

Generate a unique test recipient for sign-up, verification, password-reset, or magic-link flows. The agent can wait from an exact timestamp checkpoint, inspect the resulting message, and use extracted code or URL candidates to continue the requested test.

Verify email for existing accounts

Use the full Mailisk address of an existing test account to check notifications, receipts, security alerts, and other application email. A wait searches the previous five minutes by default, while email history helps diagnose missing messages, duplicate sends, and ordering.

Test SMS codes and links

Wait for inbound text messages and search SMS history for codes or links in verification, passwordless sign-in, and other application flows.

Exercise outbound email workflows

Send new email, reply to or forward a received message, and inspect queue state, recipient delivery states, and provider events. External recipients must be verified, and outbound actions should only be used when the requested workflow requires sending data outside Mailisk.

Available tools

Inbound email

Tool	Description	Required scopes
generate_test_email_address	Generate a unique, unreserved test recipient address and timestamp checkpoint in an accessible namespace.	namespace:read
wait_for_email	Wait for a matching inbound email to a full generated or existing Mailisk recipient address, using an exact checkpoint or a five-minute recent window by default.	namespace:read, email:read
search_emails	Search recent inbound email metadata for an exact recipient or across a namespace, newest first, with filters and pagination.	namespace:read, email:read
get_email	Fetch a known inbound email by ID, including extracted code and URL candidates and optional body fields.	namespace:read, email:read

Outbound email

Tool	Description	Required scopes
send_email	Queue a new email from a Mailisk namespace to as many as four recipients.	email:send
reply_to_email	Queue a threaded reply to a known inbound email.	email:read, email:send
forward_email	Forward a known inbound email to explicit recipients.	email:read, email:send
get_outbound_email_status	Inspect queue state, recipient delivery states, and provider events for an outbound email.	email:send

SMS

Tool	Description	Required scopes
list_sms_numbers	List accessible provider and virtual test numbers and return a timestamp checkpoint for a new test flow.	sms:read
search_sms	Search SMS history for one Mailisk number, newest first, with filters and pagination.	sms:read
wait_for_sms	Wait for a matching inbound SMS using an exact checkpoint or a five-minute recent window by default.	sms:read

Troubleshooting

• If authentication fails, confirm the key starts with sk_mcp_ and is sent as Authorization: Bearer ....
• If address generation fails for missing scopes, confirm the key has namespace:read. Email wait, search, and fetch tools need both namespace:read and email:read. Outbound sends and status inspection need email:send; reply and forward also need email:read. SMS tools need the opt-in sms:read scope.
• If no email is found, confirm the full recipient address and make sure the message arrived after the supplied checkpoint or within the recent lookback window.
• If no SMS is found, make sure the selected number is active and either the app delivery or virtual injection happened after the supplied checkpoint or within the recent lookback window.