SDKs & MCP server — what's shipping at launch

The mails.ai REST APIis available today and is the canonical interface — everything you can do, you can do over plain HTTPS. The official SDKs and MCP server are thin wrappers over that same surface, in active development, and publish at Phase 1 launch (Q3 2026). This page shows the shape they will take so you can plan around them; until they ship, build against REST (the quickstart is the fastest path).

The packages below are not on npm or PyPI yet. If a snippet here does not install, that is expected — use the REST API in the meantime. We will announce each release 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"; // publishes at Phase 1 launch

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  # publishes at Phase 1 launch

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 npx and registers five tools: mails.send, mails.on_reply, mails.list_threads, mails.suppress, and mails.get_reputation. 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, every SDK and the MCP server call the same endpoints documented in the API reference — so anything you build against REST today carries straight over when the packages land.