> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mailchannels.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Automate inbound domain management with the Provisioning API
> Use the MailChannels Inbound Provisioning API to manage domains, safelists, blocklists, downstream addresses, and console logins programmatically.
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](https://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:
```http theme={null}
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](/inbound/safelists-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.
### Generate Domain Console login links
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.