The Email API Built for AI Agents

curl -X POST https://api.multimail.dev/v1/emails/send \
  -H &"cm">#039;Authorization: Bearer $MULTIMAIL_API_KEY' \
  -H &"cm">#039;Content-Type: application/json' \
  -d &"cm">#039;{
    "from": "[email protected]",
    "to": "[email protected]",
    "subject": "API Integration Test",
    "text": "Testing MultiMail API integration. This message was sent by an AI agent.",
    "agent_id": "crm-agent-v1"
  }&"cm">#039;

"cm"># Response under gated_send oversight:
"cm"># {
"cm">#   "message_id": "msg_01HX9K3ZQABCDEF",
"cm">#   "status": "pending",
"cm">#   "oversight_mode": "gated_send",
"cm">#   "approval_url": "https://app.multimail.dev/pending/msg_01HX9K3ZQABCDEF"
"cm"># }

from multimail import MultiMailClient

client = MultiMailClient(api_key="$MULTIMAIL_API_KEY")

"cm"># Send — returns immediately with pending status under gated_send
result = client.send_email(
    from_address="[email protected]",
    to="[email protected]",
    subject="API Integration Test",
    text="Testing MultiMail API integration.",
    agent_id="crm-agent-v1",
)

print(f"Status: {result.status}")          "cm"># pending
print(f"Message ID: {result.message_id}")  "cm"># msg_01HX9K3ZQABCDEF

"cm"># Inspect what's waiting for approval
pending = client.list_pending()
for msg in pending:
    print(f"Awaiting approval: {msg.subject} → {msg.to}")

"cm"># Read incoming messages autonomously (reads are not gated)
messages = client.check_inbox(
    mailbox="[email protected]",
    limit=10,
)
for msg in messages:
    print(f"Received: {msg.subject} from {msg.from_address}")

import httpx

HEADERS = {
    "Authorization": "Bearer $MULTIMAIL_API_KEY",
    "Content-Type": "application/json",
}

"cm"># Create mailbox with gated_send (sends queue for approval, reads are autonomous)
response = httpx.post(
    "https://api.multimail.dev/v1/mailboxes",
    headers=HEADERS,
    json={
        "address": "[email protected]",
        "display_name": "Support Agent",
        "oversight_mode": "gated_send",
        "agent_id": "support-agent-v2",
    },
)
mailbox = response.json()
print(f"Created: {mailbox[&"cm">#039;address']}")
print(f"Oversight: {mailbox[&"cm">#039;oversight_mode']}")

# Later: promote to monitored once trust is established
httpx.patch(
    f"https://api.multimail.dev/v1/mailboxes/{mailbox[&"cm">#039;id']}",
    headers=HEADERS,
    json={"oversight_mode": "monitored"},
)
print("Promoted to monitored — agent now sends autonomously with notifications")

from flask import Flask, request, jsonify
import hmac, hashlib

app = Flask(__name__)
WEBHOOK_SECRET = "whsec_your_webhook_secret"

@app.route("/webhooks/multimail", methods=["POST"])
def handle_multimail_event():
    sig = request.headers.get("X-MultiMail-Signature", "")
    body = request.get_data()
    expected = hmac.new(
        WEBHOOK_SECRET.encode(), body, hashlib.sha256
    ).hexdigest()
    if not hmac.compare_digest(sig, f"sha256={expected}"):
        return jsonify({"error": "invalid signature"}), 401

    event = request.json

    if event["type"] == "email.approved":
        message_id = event["data"]["message_id"]
        resume_agent_workflow(message_id)

    elif event["type"] == "email.rejected":
        message_id = event["data"]["message_id"]
        reason = event["data"].get("rejection_reason", "no reason given")
        handle_rejection(message_id, reason)

    return jsonify({"received": True})

def resume_agent_workflow(message_id: str):
    print(f"Email {message_id} approved and delivered — continuing workflow")

def handle_rejection(message_id: str, reason: str):
    print(f"Email {message_id} rejected: {reason}")

"cm">// ~/.config/claude/claude_desktop_config.json
{
  "mcpServers": {
    "multimail": {
      "command": "npx",
      "args": ["-y", "@multimail/mcp-server"],
      "env": {
        "MULTIMAIL_API_KEY": "$MULTIMAIL_API_KEY"
      }
    }
  }
}

"cm">// Claude Desktop can then invoke tools directly, for example:
"cm">//
"cm">// Tool: create_mailbox
"cm">// { "address": "[email protected]", "oversight_mode": "gated_send" }
"cm">//
"cm">// Tool: send_email
"cm">// { "from": "[email protected]",
"cm">//   "to": "[email protected]",
"cm">//   "subject": "API Integration Test",
"cm">//   "text": "Testing MultiMail API integration." }
"cm">//
"cm">// Tool: list_pending
"cm">// {}  — returns all messages awaiting human approval
"cm">//
"cm">// Tool: check_inbox
"cm">// { "mailbox": "[email protected]", "limit": 20 }