multimail

Python SDK for the MultiMail API — email infrastructure for AI agents.

Installation

pip install multimail

Quick Start

from multimail import MultiMail

mm = MultiMail("mm_live_your_api_key")

# List mailboxes
mailboxes = mm.list_mailboxes()
mailbox_id = mailboxes[0]["id"]

# Send an email
result = mm.send_email(
    mailbox_id,
    to=["recipient@example.com"],
    subject="Hello from my agent",
    markdown="This email was sent by an AI agent using **MultiMail**.",
)
print(result)  # {"id": "...", "status": "pending_scan", "thread_id": "..."}

# Check inbox
emails = mm.list_emails(mailbox_id, direction="inbound")

# Read a specific email
email = mm.get_email(mailbox_id, emails["emails"][0]["id"])
print(email["subject"], email["text_body"])

Async Support

from multimail import AsyncMultiMail

async with AsyncMultiMail("mm_live_your_api_key") as mm:
    mailboxes = await mm.list_mailboxes()
    result = await mm.send_email(
        mailboxes[0]["id"],
        to=["recipient@example.com"],
        subject="Async email",
        markdown="Sent asynchronously!",
    )

Oversight & Approval

MultiMail supports graduated oversight modes. When a mailbox uses gated_send, emails require human approval:

# List emails waiting for approval
pending = mm.list_pending()

# Approve or reject
mm.decide(pending[0]["id"], "approve")
mm.decide(pending[1]["id"], "reject", reason="Not relevant")

All Methods

Account

• get_account() / update_account(**fields) / delete_account()

Mailboxes

• list_mailboxes() / create_mailbox(address, display_name, oversight_mode=...) / update_mailbox(id, **fields) / delete_mailbox(id)

Emails

• list_emails(mailbox_id) / get_email(mailbox_id, email_id) / send_email(mailbox_id, to=, subject=, markdown=) / reply_email(mailbox_id, email_id, markdown=) / cancel_email(mailbox_id, email_id) / get_thread(mailbox_id, thread_id) / download_attachment(mailbox_id, email_id, filename)

Tags

• get_tags(mailbox_id, email_id) / set_tags(mailbox_id, email_id, tags) / delete_tag(mailbox_id, email_id, key)

Contacts

• list_contacts(q=) / add_contact(email, name=) / delete_contact(contact_id)

Oversight

• list_pending() / decide(email_id, action, reason=)

API Keys

• list_api_keys() / create_api_key(name, scopes=) / revoke_api_key(key_id)

Webhooks

• list_webhooks() / create_webhook(url, events, secret=) / delete_webhook(webhook_id)

Domains

• list_domains() / add_domain(domain) / verify_domain(domain_id) / delete_domain(domain_id)

Suppression

• list_suppressions() / remove_suppression(address)

Usage & Audit

• get_usage() / get_audit_log(limit=)

Error Handling

from multimail import MultiMail, AuthenticationError, RateLimitError

mm = MultiMail("mm_live_your_api_key")
try:
    mm.send_email(mailbox_id, to=["test@example.com"], subject="Hi", markdown="Hello")
except AuthenticationError:
    print("Invalid API key")
except RateLimitError as e:
    print(f"Rate limited, retry after {e.retry_after}s")

Links

• MultiMail — Homepage
• API Docs — Full API reference
• MCP Server — For Claude, Cursor, and other MCP clients