Create and manage domains with the REST API
The Domain Provisioning API is a JSON REST API for partners and server administrators. With a scoped bearer token you can check whether a domain is free, create a domain with its admin account, update limits and expiry, and delete it. Ask your server administrator for a token and the API address. Requests support idempotency keys and are audit-logged.
For: Server adminWebTime-saving
How to create and manage domains with the rest api
- Ask your server administrator for a bearer token with the scopes you need, and the API address.
- Send each request over HTTPS with the token in the Authorization header.
- Add an Idempotency-Key header to create requests, so a retry never creates a domain twice.
- Read the typed error code in any failed response and handle it.
Example
A reseller's billing portal calls the API the moment a customer pays. It checks the domain name, creates a 50-user domain with its admin account and a storage allowance, and stores the request id for its records.
Operations
| Operation | What it does | Scope needed |
|---|---|---|
| Check domain | Tells you whether a domain is already registered. | domain:read |
| Authenticate admin | Confirms a domain administrator's credentials. | domain:read |
| Create domain | Creates the domain and its administrator account. | domain:write |
| Update domain | Changes users allowed, storage or expiry. | domain:write |
| Delete domain | Removes the domain. | domain:delete |
Create fields
| Field | Meaning |
|---|---|
| domain | The domain name, for example acme.in |
| adminUsername, adminPassword | The first domain administrator |
| usersAllowed | Maximum number of mailboxes |
| totalSpaceAllowedMb | Total storage for the domain, in MB |
| adminUserAllowedSpaceMb | Mailbox size for the administrator, in MB |
| expiryDate | When the domain's subscription ends |
Good to know
- Each token carries only the scopes it was issued with. Give a portal that only creates domains no delete scope.
- Errors come back with a code, for example DOMAIN_ALREADY_REGISTERED when the domain exists.
- Every request gets a request id and is written to an audit log.
Was this page helpful?
Updated 2026-10-28