API documentation

Welcome to Mailcheap’s New Mail System (NMS) API v1 documentation. Contact us for corrections, additions or general feedback.

General information

This HTTP API is built around ReST principles. It accepts and responds with JSON data (application/json mimetype, UTF-8 character encoding) unless stated otherwise. Notable exceptions:

  • HTTP 204 NO CONTENT responses are an empty string in text/html mimetype.
  • Uncaught exceptions due to program error (very rare) are in text/html mimetype.
  • Gateway timeouts due to server overload are in text/html mimetype.

All routes requiring authentication must use Basic access authentication and provide a header like: Authorization: Basic <username:auth_token> where auth_token is the authorization token obtained after authenticating with your login credentials (username & password) and the part within (but not including) angle brackets is base64 encoded.

Examples provided are in Python 3. Examples in curl are provided for authentication routes.

Replace placeholder values in the documentation with actual values. For example, replace example.domain.tld with your own mailserver hostname.

Rate limits

  • Variable, 15-20 requests per second per IP address

Your IP may be banned for 1 or more hours if the above limits are crossed multiple times.

Dedicated services can enable custom rate limits and whitelisting of trusted IPs by opening a support ticket.

API Index


Two-factor authentication (2FA)

Passwordless authentication

Password authentication

Account recovery



Domain aliases

Relay domains


Sender addresses

Global antispam thresholds

Per-domain antispam thresholds

Global whitelist & blacklist rules

Per-domain whitelist & blacklist rules

Auto migration setup

Auto migration users

Auto migration resync


Contacts sharing


Calendar sharing

Sieve filtering

Vacation autoresponder

Webmail password