Overview

MX API Documentation

Configure domains, manage mailboxes, sync mail, and subscribe to mailbox events from a single API.

API Reference Auth Guide

Quickstart

  1. Set env vars in .env or shell (MX_API_KEYS, Postgres, IMAP, JWT).
  2. Start the server: npm run dev.
  3. Open http://127.0.0.1:3000/docs for docs.
  4. Use the API key from MX_API_KEYS for /v2 routes.

Domains

Provision a domain, generate DKIM, and track DNS verification.

Go to Domains

Email Accounts

Create inboxes, reset passwords, and manage account status.

Go to Accounts

Mail Sync

Use incremental sync and fetch messages or attachments.

Go to Mail

Core concepts

Authentication. /v2 routes use x-api-key. Mail routes require JWT.

Rate limits. 60 requests per minute per IP.

Realtime events. Connect to /ws for mailbox change notices.

Common headers

Authorization: Bearer YOUR_JWT
x-api-key: YOUR_API_KEY
x-dovecot-signature: hex_hmac

Webhook requests must be signed using the raw request body.

Explore the API

Use the reference page for every route and example request.

Browse API Reference

Service endpoints

These endpoints serve the documentation UI and assets.

Method Path Description
GET / Docs home page (same as /docs).
GET /docs Docs home page.
GET /docs/* Static docs files (HTML, CSS, JS, images, markdown).

Examples

curl -i "http://127.0.0.1:3000/"
curl -i "http://127.0.0.1:3000/docs/reference.html"

Notes

These routes are public and do not require authentication.

If you deploy behind a proxy, ensure it forwards /docs paths.