Documentation
Guides

SDKs & MCP server

4 min read

The mails.ai REST APIis the canonical interface — everything you can do, you can do over plain HTTPS. The TypeScript SDK (@mailsai/sdk) and the MCP server (@mailsai/mcp-server) are live on npm today as thin wrappers over that same surface. The Python SDK (mailsai) is coming next— until it lands, build against REST or the TypeScript SDK (the quickstart is the fastest path).

The TypeScript SDK and MCP server install today (npm i @mailsai/sdk, npx @mailsai/mcp-server). The Python mailsaipackage is not on PyPI yet — use REST or TypeScript for now; we’ll announce it on the changelog.

TypeScript — @mailsai/sdk

The TypeScript SDK gives you a typed client that reads MAILS_API_KEY from the environment, an agent factory, and typed reply handling:

import { mails } from "@mailsai/sdk"; // npm i @mailsai/sdk — live on npm

const sarah = mails.agent("sarah", { domain: "acme.mails.ai" });

await sarah.send({
  to: "user@example.com",
  subject: "Welcome aboard",
});

sarah.onReply((reply) => {
  // reply.injection_score, reply.sender_reputation always present
  // reply.intent, reply.entities with opt-in classification
});

Python — mailsai

The Python SDK mirrors the same surface, idiomatically:

from mailsai import agent  # coming soon — build on REST or @mailsai/sdk today

sarah = agent("sarah", domain="acme.mails.ai")

sarah.send(to="user@example.com", subject="Welcome aboard")

@sarah.on_reply
def handle(reply):
    # reply.injection_score, reply.sender_reputation
    # reply.intent, reply.entities with opt-in classification
    ...

MCP server — @mailsai/mcp-server

The MCP server exposes mails.ai as tools to any MCP-capable runtime — Claude Code, Cursor, Cline, Continue, the OpenAI Agents SDK. It runs client-side via npxand registers the full mails.ai toolset — mails.send, mails.reply, mails.list_threads, mails.suppress, mails.get_reputation, and more. Add it with one config block:

{
  "mcpServers": {
    "mails": {
      "command": "npx",
      "args": ["-y", "@mailsai/mcp-server"],
      "env": {
        "MAILS_API_KEY": "mk_live_..."
      }
    }
  }
}

Per-runtime setup walkthroughs (where the config file lives for each tool) are already on the integrations pages. Under the hood, the SDK and the MCP server call the same endpoints documented in the API reference — so anything you build against REST carries straight over to the SDK, and vice-versa.

Getting started
Quickstart — build against REST today.
Integrations
MCP runtime setups — Claude Code, Cursor, and more.