Mails.ai with the OpenAI Agents SDK — MCP server or function tools

The OpenAI Agents SDK ships first-class MCP support via the MCPServerStdio constructor. Your agent picks up mails.send, mails.on_reply, mails.list_threads, mails.suppress, and mails.get_reputationautomatically — same surface as Claude Code, native to the SDK’s own tool-calling loop.

Why OpenAI Agents SDK + mails.ai

The Agents SDK is OpenAI’s opinionated framework for multi-agent systems — handoffs, state management, traces, and tool calling all defined as first-class primitives. Wiring email as an MCP server means each agent in your system can autonomously send, read, and triage email without per-agent boilerplate. Sales agents handle leads, support agents handle tickets, ops agents handle alerts — all on the same mails.ai network with per-agent identity and reputation.

Path A — MCPServerStdio (recommended)

The install card above shows the canonical pattern. To break it down:

import { Agent, MCPServerStdio, run } from "@openai/agents";

// 1. Spawn the mails.ai MCP server. Runs in your process via npx.
const mailsServer = new MCPServerStdio({
  name: "mails",
  command: "npx",
  args: ["-y", "@mailsai/mcp-server"],
  env: { MAILS_API_KEY: process.env.MAILS_API_KEY! },
});

// 2. Pass to your Agent. Tools auto-discover at session start.
const sarah = new Agent({
  name: "sarah",
  instructions: `
    You are a sales operations agent. Use mails.* tools to send and read
    email on behalf of yourcompany.com.

    For inbound replies, check event.injection_score before acting.
  `,
  mcpServers: [mailsServer],
});

// 3. Run as normal. The model picks tools by name.
const result = await run(sarah, "Email lead@example.com a follow-up.");

That is the entire setup. The model sees five new tools (mails.send, mails.on_reply, mails.list_threads, mails.suppress, mails.get_reputation) and calls them by name when the user request implies email work. No glue code on your side.

Path B — function tools (custom control)

For cases where you want fine-grained control over tool exposure or argument validation, wrap the mails.ai REST API as @function tools:

import { Agent, tool, run } from "@openai/agents";
import { z } from "zod";
import { mails } from "@mailsai/sdk";

const client = mails({ apiKey: process.env.MAILS_API_KEY! });

const sendEmail = tool({
  name: "send_email",
  description: "Send an email from the named agent.",
  parameters: z.object({
    to: z.string().email(),
    subject: z.string(),
    body: z.string(),
  }),
  execute: async ({ to, subject, body }) => {
    // Custom guard: require subject to be at least 5 chars
    if (subject.length < 5) throw new Error("Subject too short");

    const result = await client.agent("sarah").send({ to, subject, body });
    return { send_id: result.id, pool: result.pool };
  },
});

const sarah = new Agent({
  name: "sarah",
  instructions: "Send sales follow-ups via the send_email tool.",
  tools: [sendEmail],
});

Use this path when:

• You want only a subset of mails.ai capabilities (just send, not list_threads).
• You want to enforce additional validation (e.g., recipient allowlist).
• You want to transform the response before passing back to the model.
• You are pre-MCP-runtime support and need to fall back.

For most users: Path A. For the long tail: Path B.

Common patterns

• Multi-agent sales workflow: a triage agent reads inbound, classifies intent, and hands off to a specialist agent (demo-scheduler, refund-handler, tier-upgrade) — each holding its own mails.ai key for per-agent reputation.
• Long-running outbound campaigns: a campaign agent loops through leads, calls mails.send with rate-limit awareness, and tracks results via mails.list_threads for follow-ups.
• Support escalation pipeline: inbound triage agent reads typed events, escalates urgency > 0.7 to a senior-support agent (with handoff + context preservation), and replies via mails.send.

Security considerations

• Per-key scope.One mails.ai key per OpenAI agent. The SDK’s handoff preserves the receiving agent’s MCP servers, so identity stays correct across handoffs.
• Injection guard. When your agent reads inbound: if (event.injection_score > 0.5) return;. See that post.
• Tool tracing. All MCP tool calls appear in the standard Agents SDK trace output. Correlate with mails.ai dashboard send IDs for end-to-end visibility.
• Concurrency. The MCP server is process-per-agent-runtime by default. For high-concurrency apps, deploy a shared MCP server gateway (Phase 2 ships official guidance) instead of spawning per-request.

Read the MCP-native email post for the broader thesis, or compare against the Anthropic SDK setup for cross-vendor coverage.