API Reference Overview

The MoMail API is organized around REST principles with predictable resource-oriented URLs. All API access is over HTTPS and returns JSON.

Base URL

https://api.momail.io/v1

All API requests require authentication via an API key in the X-API-Key header:

X-API-Key: mk_xxxxxxxxxxxxxxxx_xxxxxxxxxxxxxxxx

See Authentication for more details.

All responses follow a consistent envelope format:

{
  "success": true,
  "data": { ... },
  "meta": { ... }
}

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Error description",
    "details": { ... }
  }
}

Auth User authentication and session management

Domains Domain registration, verification, and management

Mailboxes Create mailboxes, validation rules, and error responses

API Keys Create and manage API keys

Search Semantic email search with vector similarity

Webhooks Configure webhook endpoints and event handling

Billing Subscription and usage information

Method	Description
`GET`	Retrieve a resource or list of resources
`POST`	Create a new resource
`PUT`	Update an existing resource (full replacement)
`PATCH`	Partially update a resource
`DELETE`	Remove a resource

Many endpoints support these common parameters:

Parameter	Type	Description
`limit`	integer	Maximum number of results (default: 20, max: 100)
`offset`	integer	Number of results to skip (for pagination)
`sort`	string	Field to sort by (e.g., `created_at:desc`)

List endpoints return paginated results:

{
  "success": true,
  "data": [ ... ],
  "meta": {
    "total": 150,
    "limit": 20,
    "offset": 0,
    "hasMore": true
  }
}

To fetch the next page:

curl https://api.momail.io/v1/domains?offset=20&limit=20 \
  -H "X-API-Key: your_key"

All dates are returned in ISO 8601 format:

2024-01-15T10:30:00.000Z

Official SDKs available:

The current API version is v1. The version is included in the base URL:

https://api.momail.io/v1/...

When we release a new API version, we will provide at least 6 months notice before deprecating the previous version.