Documentation

Everything you need to integrate Docmailer into your applications and AI agents.

Quick Start

Get started with Docmailer in 3 simple steps:

1. Create an account at docmailer.org/dashboard
2. Get your API token from the dashboard
3. Start making requests to receive and send test emails

curl https://docmailer.org/mcp/inbox \
  -H "Authorization: Bearer YOUR_TOKEN"

Authentication

All API requests require authentication via Bearer token. Include your token in the Authorization header:

Authorization: Bearer YOUR_TOKEN

You can also pass the token as a query parameter:

https://docmailer.org/mcp/inbox?token=YOUR_TOKEN

Get Inbox

Returns your test email address and a list of received emails.

{
  "success": true,
  "inbox": {
    "id": "...",
    "email": "yourname@docmailer.org"
  },
  "emails": [...]
}

List Emails

Returns all emails in your inbox with previews.

Read Email

Returns the full content of a specific email, including text and HTML body.

Send Email

Send an email from your test inbox. Pro plan required. Supports file attachments.

Attachments

You can send file attachments with your emails. Each attachment should include:

• filename - Name with extension (e.g., "report.pdf")
• content - File content as base64 string

Allowed file types: PDF, Excel (.xlsx, .xls), Word (.docx, .doc)

Size limits: 5MB per file, 10MB total per email

curl -X POST https://docmailer.org/mcp/send \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "recipient@example.com",
    "subject": "Report attached",
    "text": "Please find the report attached.",
    "attachments": [{
      "filename": "report.pdf",
      "content": "JVBERi0xLjQK..."
    }]
  }'

Delete Email

Delete a specific email from your inbox.

MCP Setup

Docmailer supports the Model Context Protocol (MCP) for seamless integration with AI agents. Here's how to set it up with popular tools.

Claude Code

Claude Code supports MCP servers natively with OAuth authentication. Add Docmailer with one command:

# Add Docmailer MCP server
claude mcp add docmailer --transport http https://docmailer.org/mcp

# Verify it's added
claude mcp list

# Check status inside Claude Code
/mcp

When you first connect, Claude Code will open a browser window for OAuth authentication. Enter your API token from the dashboard to authorize.

Alternatively, edit your config file directly:

{
  "mcpServers": {
    "docmailer": {
      "type": "streamable-http",
      "url": "https://docmailer.org/mcp"
    }
  }
}

Config file locations:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

After adding, restart Claude Code. Then try: "Check my Docmailer inbox for new emails"

OpenAI Codex CLI

Codex CLI supports MCP servers through its config file. Add Docmailer to ~/.codex/config.toml:

# Add Docmailer MCP server
[[mcp_servers]]
name = "docmailer"
transport = "http"
url = "https://docmailer.org/mcp"

Or use the Codex CLI commands:

# Add the server
codex mcp add docmailer --transport http --url "https://docmailer.org/mcp"

# List configured servers
codex mcp list

Once configured, Codex will automatically load the Docmailer tools when starting a session. OAuth authentication will be handled automatically.

OpenCode

OpenCode supports MCP servers via its JSON config. Add Docmailer using the CLI or config file:

opencode mcp add docmailer --type remote --url https://docmailer.org/mcp

Or add directly to your config file:

{
  "mcp": {
    "docmailer": {
      "type": "remote",
      "url": "https://docmailer.org/mcp",
      "enabled": true
    }
  }
}

Troubleshooting: Server shows red/disconnected

OpenCode has a known issue with type: "remote" MCP servers where the connection fails silently. If the Docmailer server shows as disconnected, use the local proxy workaround instead:

{
  "mcp": {
    "docmailer": {
      "type": "local",
      "command": ["npx", "-y", "mcp-remote", "https://docmailer.org/mcp"],
      "enabled": true
    }
  }
}

This uses mcp-remote to bridge the remote server over stdio, which OpenCode handles reliably.

Other AI Agents

Any MCP-compatible agent can connect to Docmailer using Streamable HTTP transport:

# Streamable HTTP endpoint (recommended)
https://docmailer.org/mcp

# Legacy SSE endpoint (deprecated)
https://docmailer.org/mcp/sse?token=YOUR_TOKEN

# Supports standard MCP methods:
# - initialize
# - tools/list
# - tools/call

OAuth 2.0 is supported for secure authentication. The server implements dynamic client registration (RFC 7591).

MCP Tools

When connected via MCP, the following tools are available to your AI agent: