Use mailfloss from AI agents (MCP)

6 min

mailfloss runs a remote MCP server at https://api.mailfloss.com/mcp. It exposes the v1 REST API as tools, so an AI agent in Claude, ChatGPT, Cursor or any other MCP client can verify an address, verify a list, or check your account in the middle of a task.

Every tool call is the equivalent REST call, made with your credentials. It has the same org scoping, credits, rate limits and error envelope.

Connect

There are two ways to authenticate: sign in with OAuth, or send an API key.

Add the server with no credentials. Your client opens a browser, you sign in to the mailfloss dashboard, and you approve the connection.

claude mcp add --transport http mailfloss https://api.mailfloss.com/mcp

In Claude (web, desktop or mobile) or ChatGPT, add https://api.mailfloss.com/mcp as a custom connector. Any MCP client that supports OAuth works the same way, as long as its redirect URI is one we accept: a loopback address (http://localhost, http://127.0.0.1 or http://[::1], any port) or the callback of a supported client. Other clients can use an API key.

The connection acts as you, with your dashboard role's access. Access tokens last one hour and refresh automatically. To disconnect a client, open Account Settings → Connected apps and click Disconnect.

An MCP sign-in works only on /mcp, not on the REST API. To call the REST API with OAuth, build an app.

API key

Send your API key as a Bearer token, exactly as for the REST API. Create a key in the mailfloss dashboard under Developers → API keys.

Claude Code

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

Cursor: add this to ~/.cursor/mcp.json, or to the project's .cursor/mcp.json:

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

Any client that supports MCP Streamable HTTP with custom headers works the same way. The key must be in the Authorization header. A key in the URL doesn't work: the client connects, but every tool call fails with 401. A request with no credential gets 401 Unauthorized.

Send one JSON-RPC request per POST; batching isn't supported. Each POST counts once against your API rate limit, and the REST call a tool makes doesn't count again.

Tools

Tool	REST call	Cost
verify_email	GET /v1/verify	1 credit per call
start_batch_verification	POST /v1/batch-verify	1 credit per email
get_batch_status	GET /v1/batch-verify/{id}/status	free
get_batch_results	GET /v1/batch-verify/{id}/results	free
cancel_batch	POST /v1/batch-verify/{id}/cancel	changes the account (refunds unprocessed credits)
get_organization	GET /v1/organization	free
get_account	GET /v1/account	free
list_integrations	GET /v1/integrations	free
get_integration	GET /v1/integrations/{type}	free
get_connection	GET /v1/integrations/{type}/connections/{id}	free
connect_integration	POST /v1/integrations/{type}/connections	changes the account
update_settings	PATCH /v1/integrations/{type}/connections/{id}	changes the account
disconnect_integration	DELETE /v1/integrations/{type}/connections/{id}	changes the account
resync_integration	POST /v1/integrations/{type}/connections/{id}/sync	refreshes stored audiences
test_integration	POST /v1/integrations/{type}/connections/{id}/test	free
get_usage_report	GET /v1/reports/usage	free
list_jobs	GET /v1/jobs	free

Tools that spend credits or change the account say so in their description. Read-only tools carry readOnlyHint: true. verify_email and resync_integration carry readOnlyHint: false. start_batch_verification, cancel_batch, connect_integration, update_settings and disconnect_integration also carry destructiveHint: true. These annotations are hints. Whether your client asks you to confirm a credit-spending or account-changing call depends on its own permission settings, so check them before you turn on auto-approval.

A tool's result is the REST response body. When the REST call fails, the tool returns an error result whose text is the v1 error envelope. Branch on error.code as you would with the REST API.

Example prompts

"Verify [email protected] before I add her to the newsletter."

"Verify these 40 addresses as a batch and tell me which ones are undeliverable."

"How many credits do I have left this month?"

"Is my Klaviyo integration still connected, and are its credentials still working?"

Not yet supported