Admin API#

The Admin API lets you manage mail domains, accounts, aliases, quotas, and routing programmatically. It is intended for provisioning scripts, monitoring integrations, and tenants that want to embed mail management into their own control panel.

Base URL#

https://mail.novaza.ai/api/admin/v1

Authentication#

Requests must include a bearer token issued to an admin account or a service account with the mail.admin role.

Authorization: Bearer <token>

Tokens are created from SSO → Users → API keys and can be scoped to individual domains.

Resources#

Domains#

GET /domains — list domains
POST /domains — add a new domain
DELETE /domains/{domain} — remove a domain

Accounts#

GET /accounts — list accounts (supports ?domain= and pagination)
POST /accounts — create an account
GET /accounts/{email} — retrieve a single account
PATCH /accounts/{email} — update quota, display name, status
DELETE /accounts/{email} — remove an account

Aliases#

GET /aliases — list aliases
POST /aliases — create an alias
DELETE /aliases/{alias} — remove an alias

Quotas#

GET /quotas/{email} — retrieve usage and limit
PUT /quotas/{email} — set a new quota limit

Example#

Create a new mailbox:

curl -X POST https://mail.novaza.ai/api/admin/v1/accounts \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "alice@example.com",
    "display_name": "Alice",
    "password": "<initial-password>",
    "quota_bytes": 5368709120
  }'

Rate Limits#

The Admin API is limited to 60 requests per minute per token. Exceeding the limit returns HTTP 429 with a Retry-After header.

Errors#

All errors return a JSON body:

{ "error": { "code": "account_exists", "message": "Account already exists" } }

Common codes: unauthorized, forbidden, not_found, validation_failed, quota_exceeded, rate_limited.