SDKs & MCP server

The mails.ai REST API is 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, and the Python SDK (mailsai) is live on PyPI. If you would rather not add a dependency, the quickstart makes the same calls over plain REST.

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 hello = mails.agent("hello");

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

hello.onReply((reply) => {
  // reply.injection_score, reply.sender_reputation always present
  // reply.intent is "general_reply": intent and entities are read only from first-contact mail, with classification on
});

Python — mailsai

The Python SDK mirrors the same surface, idiomatically:

from mailsai import agent  # pip install mailsai — live on PyPI

hello = agent("hello")

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

@hello.on_reply
def handle(reply):
    # reply.injection_score, reply.sender_reputation
    # reply.intent is "general_reply": intent and entities are read only from first-contact mail, with classification on
    ...

hello.start_listening()  # blocks, calling handle() for each reply

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 npx and registers the full mails.ai toolset — mails_send, mails_reply, mails_list_threads, mails_check_suppression, 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, and the MCP server page covers the hosted server, which keeps your key out of the config. 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.