Claude Agent SDK Email Integration

Why This Pairing Works

The Claude Agent SDK is Anthropic's framework for building autonomous agents on the same harness that powers Claude Code — it was renamed from the Claude Code SDK in September 2025 and ships in both Python and TypeScript. MCP servers are the first-class way to add tools to it, and Dead Simple's email API is exposed as a hosted MCP server at https://api.deadsimple.email/mcp. That means a Claude agent gets full email — create inboxes, send, receive, reply, wait for OTPs — from a single config entry, with no glue code.

Quick Start: .mcp.json

If your agent runs in a project directory (or you're using Claude Code itself), declare the server in .mcp.json at the project root. The SDK picks it up automatically:

{
  "mcpServers": {
    "deadsimple": {
      "type": "http",
      "url": "https://api.deadsimple.email/mcp",
      "headers": {
        "Authorization": "Bearer dse_your_api_key"
      }
    }
  }
}

Tools arrive namespaced as mcp__deadsimple__* — e.g. mcp__deadsimple__send_email, mcp__deadsimple__get_verification_code — so you can allow exactly the ones your agent should have.

Programmatic Config (Python)

For agents built in code, pass the server config through ClaudeAgentOptions.mcp_servers. Use allowed_tools to scope what the agent can touch:

import os, asyncio
from claude_agent_sdk import query, ClaudeAgentOptions

options = ClaudeAgentOptions(
    mcp_servers={
        "deadsimple": {
            "type": "http",
            "url": "https://api.deadsimple.email/mcp",
            "headers": {"Authorization": f"Bearer {os.environ['DSE_API_KEY']}"},
        }
    },
    allowed_tools=[
        "mcp__deadsimple__create_inbox",
        "mcp__deadsimple__send_email",
        "mcp__deadsimple__read_messages",
        "mcp__deadsimple__reply_to_message",
        "mcp__deadsimple__wait_for_email",
    ],
)

async def main():
    async for message in query(
        prompt="Create an inbox called 'support', send a welcome email "
               "to hello@example.com, and summarize any reply that arrives "
               "in the next two minutes.",
        options=options,
    ):
        print(message)

asyncio.run(main())

Programmatic Config (TypeScript)

The TypeScript SDK takes the same shape in options.mcpServers:

import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
  prompt: "Create an inbox and send a test email to hello@example.com",
  options: {
    mcpServers: {
      deadsimple: {
        type: "http",
        url: "https://api.deadsimple.email/mcp",
        headers: { Authorization: `Bearer ${process.env.DSE_API_KEY}` },
      },
    },
    allowedTools: ["mcp__deadsimple__create_inbox", "mcp__deadsimple__send_email"],
  },
})) {
  console.log(message);
}

Prefer a local process over a remote server? Both SDKs accept a stdio config instead — install pip install "deadsimple-email[mcp]" and swap the server entry for:

{
  "deadsimple": {
    "command": "python",
    "args": ["-m", "deadsimple.mcp"],
    "env": { "DSE_API_KEY": "dse_your_api_key" }
  }
}

What the Agent Can Do

The server exposes 14 tools: create_inbox, list_inboxes, delete_inbox, send_email, read_messages, read_message, reply_to_message, forward_message, wait_for_email, get_verification_code, get_verification_link, list_threads, read_thread, and get_usage. The verification tools matter most for autonomous agents: wait_for_email blocks until a matching message arrives, and get_verification_code / get_verification_link return the extracted OTP or magic link directly — so an agent can complete a signup flow end to end without parsing raw MIME.

Alternative: an Agent Skill

If you'd rather teach the agent the API than hand it typed tools, drop a SKILL.md into .claude/skills/deadsimple-email/ describing the REST endpoints (or the deadsimple-email Python SDK) and let the agent use its built-in Bash tool:

---
name: deadsimple-email
description: Send and receive email through the Dead Simple Email API.
  Use when a task requires creating an inbox, sending mail, or waiting
  for a verification code.
---

# Dead Simple Email

Base URL: https://api.deadsimple.email
Auth header: Authorization: Bearer $DSE_API_KEY

- Create inbox:  POST /v1/inboxes            {"display_name": "..."}
- Send email:    POST /v1/inboxes/{id}/messages
                 {"to": ["..."], "subject": "...", "text_body": "..."}
- List messages: GET  /v1/inboxes/{id}/messages
- Latest OTP:    GET  /v1/inboxes/{id}/verification

MCP is less setup and gives the model typed tools; a skill gives you full control over the instructions and works even where MCP servers are locked down. They combine fine, too.

FAQ

Related Integrations

• MCP Server — the underlying MCP server, plus Claude Desktop / Cursor / Windsurf configs
• Hermes Agent — same remote MCP server in Nous Research's agent runtime
• Strands Agents — AWS's agent SDK with the same MCP connection
• Pydantic AI — type-safe Python agents with Dead Simple tools
• Python SDK — call the API directly from skills or hooks