Skip to main content
The MailChannels Inbound Provisioning API gives you full programmatic control over your inbound filtering configuration. Instead of managing domains one by one through the Host Console, you can provision and deprovision domains in bulk, manage safelists and blocklists at every tier, update downstream addresses, and generate Domain Console login links — all from your own systems or automation scripts. The full API reference, including all endpoints, request parameters, and response schemas, is available at api.mailchannels.net/inbound/v1/documentation.

​
Authentication

All requests must be made over HTTPS to the base URL: 
https://api.mailchannels.net/inbound/v1/
Authenticate by including your API key in the X-API-Key header on every request: 
X-API-Key: your-api-key-here
Requests without a valid API key are rejected with a 401 Unauthorized response. API keys are created and managed in the Host Console under Settings > Account > API Keys. You can create as many keys as you need, assign a description to each one to identify its purpose, and delete keys that are no longer in use. Most domain operations also require a subscriptionHandle query parameter that identifies which MailChannels subscription the domain belongs to. You can retrieve your subscription handles from the /subscriptions endpoint. The API allows up to 100 requests per second per customer. Requests that exceed this limit receive a 503 Service Temporarily Unavailable response.

​
What you can do

​
Manage domains

  • Provision or deprovision up to 1,000 domains in a single request.
  • Retrieve a list of all domains associated with your account or a specific API key.
  • Update domain settings, including spam handling policy, domain admins, and downstream addresses.
  • Create or remove domain aliases.
  • Associate or re-associate a domain with a specific API key.

​
Manage safelists and blocklists

The API supports list management at all three tiers of the MailChannels filtering hierarchy. See Safelists and blocklists for how these tiers interact.
  • Account-level lists — Add, remove, or retrieve entries in the global safelist or blocklist that applies across all domains in your account.
  • Domain-level lists — Add, remove, or retrieve entries in the safelist or blocklist for a specific domain.
  • User-level lists — Add, remove, or retrieve entries in the safelist or blocklist for a specific mailbox user. You can also update user settings through the API.
The API uses safelist and blocklist as the list type identifiers. The older terms whitelist and blacklist are deprecated.
You can generate a time-limited login link that signs a user into the Domain Console as a domain administrator. This is useful for cPanel or WHMCS integrations where you want domain admins to access their logs and settings from within your control panel. The API supports generating login links for a single domain or in bulk for up to 1,000 domains at once.

​
Report misclassifications

Submit false positive or false negative reports directly through the API without requiring a manual support request.

​
Using multiple API keys for security

By default, any valid API key in your account can manage any domain in your account. For greater security, you can associate each domain with a specific API key. Once associated:
  • Only that key can list, edit, or deprovision the domain.
  • Other API keys cannot see or modify domains they are not associated with.
  • If a key is compromised, only the domains tied to that key are at risk.
A domain can also be left unassociated, in which case any of your API keys can manage it.

​
Example use case

If you manage inbound filtering across several shared hosting servers, you can create one API key per server and associate each server’s domains with its corresponding key. A compromise on one server exposes only that server’s domains — not your entire account.

​
How key association works

When provisioning a domain, you can pass the associate-key flag to link it with the API key making the request. You can also update a domain’s key association at any time using the PUT /domains/{domain}/api-key endpoint. When you delete an API key, all its domain associations are removed and those domains revert to being manageable by any key.
Domains provisioned through the WHM/cPanel plugin are not automatically associated with a key. Manage key associations for plugin-provisioned domains from the Host Console or via the API. Use caution when changing key associations — domains can appear to disappear from the plugin’s view if they are no longer associated with the key the plugin is configured to use. You can configure which API key the plugin uses from API Configuration in the WHM plugin settings.