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

There are two ways to connect:

• Log in with Mailisk. Use this for Claude, ChatGPT, Claude Code, and other clients that support OAuth. You approve access in the browser and there's no key to copy.
• MCP API key. Use this for CI, scripts, and clients without OAuth support.

Any member of a Mailisk organisation can use either. MCP is available on every Mailisk plan.

Access

Each connection or key is limited to one organisation and can use every Mailisk MCP tool, including tools added later. To keep a client from sending email or reading SMS, turn those tools off in the client.

Log in with Mailisk

Add the Mailisk server URL to your client:

https://api.mailisk.com/mcp

The first time the client uses Mailisk, it opens a Mailisk page in your browser:

1. Log in to Mailisk if you aren't already.
2. Pick the organisation the client can access.
3. Click Approve. The browser returns you to the client.

The connection stays active as long as the client uses it at least once every 60 days.

Claude

In Claude on the web or desktop, open Connectors in settings and add a custom connector named Mailisk with the server URL above. Click Connect to log in and approve access.

On Team and Enterprise plans, an organisation owner may need to add the connector first.

ChatGPT

Turn on developer mode in ChatGPT's settings, then create a connector with the server URL above and OAuth as the authentication method. ChatGPT opens Mailisk to log in and approve access.

Claude Code

Run this command to add Mailisk to Claude Code in every project:

claude mcp add --transport http --scope user mailisk https://api.mailisk.com/mcp

Then run /mcp inside Claude Code, select mailisk, and choose Authenticate.

Disconnect a client

Open MCP in the dashboard and find the client under Connected agents. Click Disconnect to end its access right away. You can disconnect clients you connected; admins can disconnect any.

Access also ends when the person who connected the client is removed from the organisation.

Use an MCP API key

MCP API keys are separate from regular Mailisk REST API keys. They start with sk_mcp_.

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 and give it a name.
4. Copy the generated secret immediately. It is only shown once.

Any member can create MCP keys and rename or revoke the ones they created. Admins can manage every key. Keys keep working after the person who created them leaves, so they suit CI.

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.

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 with an API key

Use this in CI or anywhere a browser login isn't possible:

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.

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.

Check that no email was sent

Ask the agent to confirm that an email didn't arrive, such as no welcome email after a failed sign-up. The wait ends with no match instead of an error, so the test can pass.

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. An organisation admin verifies external recipients under Recipients in the dashboard. Outbound actions should only be used when the requested workflow requires sending data outside Mailisk.

Available tools

Namespaces

Tool	Description
list_namespaces	List the namespaces the connection can use, with each namespace's email domain.

Inbound email

Tool	Description
generate_test_email_address	Generate a unique, unreserved test recipient address and timestamp checkpoint in an accessible namespace.
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. For an outside address captured through Mailisk SMTP, also pass namespace.
search_emails	Search recent inbound email metadata for an exact recipient or across a namespace, newest first, with filters and pagination. For an outside address captured through Mailisk SMTP, pass both.
get_email	Fetch a known inbound email by ID, including extracted code and URL candidates, attachment download URLs, and optional body and header fields.

Outbound email

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

SMS

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

Troubleshooting

• If the approval page says no organisation can be connected, ask an owner to add you to an organisation with MCP access.
• If the approval page says the request expired, start connecting again from your client. Requests expire after 10 minutes.
• If a connected client stops working, check that it's still listed under Connected agents. If it isn't, connect it again.
• If API key authentication fails, confirm the key starts with sk_mcp_ and is sent as Authorization: Bearer ....
• 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.