API Reference Overview

MoMail exposes programmatic access on the unified app worker in two ways:

• REST under /v1/api/* — mailboxes, domains, API keys, raw MIME download
• MCP at /v1/mcp — semantic search and email retrieval for AI assistants

All access is over HTTPS. REST responses are JSON unless noted (raw .eml download).

Base URL

REST routes are served on the same origin as the product:

https://momail.io/v1/api

Examples:

• GET https://momail.io/v1/api/health — no auth
• GET https://momail.io/v1/api/mailboxes — API key or Bearer token

MCP (separate protocol, not under /v1/api):

https://momail.io/v1/mcp

See MCP Overview.

Authentication

Programmatic routes require either:

• Authorization: Bearer mk_… (recommended for agents), or
• Authorization: Bearer <supabase_access_token> (dashboard session token)

Public exception: GET /v1/api/health requires no credentials.

See Authentication.

Response shapes

Many v1 routes return resource-specific JSON (for example { "mailboxes": [...] }). Errors often use:

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable explanation",
    "details": {}
  }
}

Mailbox creation success uses { "success": true, "mailbox": { ... } }. See each endpoint page for exact shapes.

Public v1 REST endpoints (current)

Method	Path	Auth	Description
GET	/v1/api/health	None	Liveness check
GET, POST	/v1/api/mailboxes	API key / Bearer	List / create mailboxes
GET	/v1/api/mailboxes/check-email	API key / Bearer	Preflight mailbox name
DELETE	/v1/api/mailboxes/{mailboxId}	API key / Bearer	Soft-delete mailbox
GET, POST	/v1/api/keys	API key / Bearer	List / create API keys
DELETE	/v1/api/keys/{id}	API key / Bearer	Revoke API key
GET	/v1/api/emails	API key / Bearer	List recent emails (paginated)
POST	/v1/api/search	API key / Bearer	Semantic search (same as MCP search_emails)
POST	/v1/api/emails/send	API key / Bearer	Send email from a mailbox
POST	/v1/api/emails/{messageId}/reply	API key / Bearer	Reply to an email
GET	/v1/api/emails/{messageId}/raw	API key / Bearer	Download raw MIME (.eml)
GET, POST	/v1/api/webhooks	API key / Bearer	List / create outbound webhooks
GET, DELETE	/v1/api/webhooks/{id}	API key / Bearer	Get / delete webhook

Dashboard session APIs

Logged-in dashboard flows use /api/* on the same host (cookies / Bearer), for example:

• /api/auth/* — Supabase auth proxy
• /api/domains — list, create, verify, migrate mailboxes, delete (session only; not in v1)
• /api/mailboxes — includes PATCH rename (session only); v1 list/create/delete unchanged
• /api/keys — UI parity with v1 where applicable
• /api/billing/*, /api/webhooks/stripe — Stripe checkout, portal, webhooks

These are documented under Auth, Webhooks, and Billing as dashboard-oriented APIs, not as /v1/api agent routes.

API Reference

Mailboxes Create, list, preflight, and delete agent mailboxes

Emails (raw MIME) Download original .eml bytes

Domains Domain registration and verification

API Keys Create and revoke API keys

Search Semantic search (REST + MCP)

Webhooks Outbound event notifications

MCP Integration StreamableHTTP endpoint and tools

Auth (dashboard) Session registration and login

Billing (dashboard) Stripe subscription and usage

HTTP methods

Method	Description
GET	Retrieve a resource or list
POST	Create a resource
DELETE	Remove or revoke a resource

Date formats

Timestamps use ISO 8601, for example 2026-01-15T10:30:00.000Z.

Versioning

The current prefix is v1 (/v1/api/..., /v1/mcp). We will announce deprecation timelines before removing a version.