Register and verify custom domains, provision subdomains, configure DKIM keys, manage catch-all routing, and query shared platform domains.
Quick Reference#
| Endpoint | Method | Required Scope | Description |
|---|---|---|---|
/v1/domains | GET | domains:read | List all available shared and verified custom domains. |
/v1/custom-domains | GET | domains:read | List custom domains with DNS health, subdomains, and alias counts. |
/v1/custom-domains | POST | domains:write | Register a new custom domain and retrieve required DNS records. |
/v1/custom-domains/:id | GET | domains:read | Retrieve detailed configuration and usage stats for a custom domain. |
/v1/custom-domains/:id | PATCH | domains:write | Configure catch-all forwarding settings and daily limits. |
/v1/custom-domains/subdomain | POST | domains:write | Provision a dedicated subdomain under a verified parent custom domain. |
/v1/custom-domains/:id/dns-records | GET | domains:read | Retrieve required DNS records and verification targets. |
/v1/custom-domains/:id/verify-dns | POST | domains:write | Trigger live multi-resolver DNS verification and activation. |
/v1/custom-domains/:id/dkim | GET | domains:read | Retrieve DKIM selector, public key, and TXT DNS values. |
/v1/custom-domains/:id/dkim | POST | domains:write | Generate and rotate a new 2048-bit RSA DKIM key pair. |
/v1/custom-domains/:id/catch-all-stats | GET | domains:read | Retrieve catch-all forwarding traffic, top senders, and rate limits. |
/v1/custom-domains/:id | DELETE | domains:write | Delete custom domain and release associated routing records. |
DNS Requirements#
To activate inbound routing and outbound email signing, publish the following DNS records with your DNS provider:
| Type | Name / Host | Target / Value | Priority | Required For |
|---|---|---|---|---|
| MX | @ or sub-host | relay.aliasfleet.com. | 10 | All domains & subdomains |
| TXT (SPF) | @ or sub-host | v=spf1 include:_spf.aliasfleet.com ~all | — | All domains & subdomains |
| CNAME (DKIM 1) | af1._domainkey | af1._domainkey._dkim.aliasfleet.com. | — | Apex / root domains only |
| CNAME (DKIM 2) | af2._domainkey | af2._domainkey._dkim.aliasfleet.com. | — | Apex / root domains only |
| TXT (DMARC) | _dmarc | v=DMARC1; p=none; | — | Apex / root domains only |
Note
Subdomain Scope: Subdomains (e.g. mail.company.com) only require MX and SPF. DKIM and DMARC policies are handled automatically by the apex domain.
List Available Domains#
GET /v1/domains
Returns all active domains available for alias creation on your account, including verified custom domains and shared platform domains.
Scope:
domains:readRate Limit: 60 req/minIdempotent: YesResponse (200 OK)#
JSON
{ "domains": [ { "id": "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d", "domain": "company.com", "type": "custom", "is_active": true, "is_verified": true }, { "id": "2b3c4d5e-6f7a-8b9c-0d1e-2f3a4b5c6d7e", "domain": "af-mail.com", "type": "shared", "is_active": true, "is_verified": true } ]}Register Custom Domain#
POST /v1/custom-domains
Registers a new custom domain. Initiates domain provisioning and returns DNS verification records.
Scope:
domains:writeRate Limit: 60 req/minIdempotent: NoRequest Body Schema#
| Field | Type | Required | Description |
|---|---|---|---|
domain | string | Yes | Fully qualified apex domain name (e.g. company.com). |
cURL Example#
Terminal
curl -X POST "https://api.aliasfleet.com/v1/custom-domains" \ -H "Authorization: Bearer afp_4a8f9c1b2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e" \ -H "Content-Type: application/json" \ -d '{ "domain": "company.com" }'Response (201 Created)#
JSON
{ "domain": { "id": "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d", "domain": "company.com", "type": "custom", "status": "pending", "is_active": false, "is_verified": false, "created_at": "2026-09-04T12:00:00.000Z" }}Error Responses#
| Status Code | Code | Error Message | Reason |
|---|---|---|---|
400 | INVALID_DOMAIN | "Please enter a valid domain name (e.g., example.com)" | Malformed domain name or invalid TLD. |
400 | RESERVED_DOMAIN | "This domain cannot be registered as a custom domain." | System domains (e.g. aliasfleet.com, localhost) are reserved. |
403 | PLAN_UPGRADE_REQUIRED | "Custom domains are not available on your current plan. Please upgrade to continue." | Free plan includes 0 custom domains. Upgrade to Pro or Business. |
403 | QUOTA_EXCEEDED | "You have reached your custom domain limit. Please upgrade your plan to add more domains." | Maximum domain quota reached (3 on Pro, 10 on Business). |
403 | SUBSCRIPTION_PAUSED | "Your subscription is currently paused. Please resume your subscription to add domains." | Subscription is paused. |
403 | PAYMENT_REQUIRED | "Your subscription is past due. Please update your payment method to add domains." | Subscription is past due. |
409 | CONFLICT | "This domain is already registered. If you own it, please verify ownership." | Domain is already registered by another account. |
Provision Subdomain#
POST /v1/custom-domains/subdomain
Creates a dedicated subdomain under an existing verified parent custom domain (e.g. mail.company.com).
Scope:
domains:writeRate Limit: 60 req/minRequest Body Schema#
| Field | Type | Required | Description |
|---|---|---|---|
parent_domain_id | string | Yes | UUID of the verified parent root domain. |
subdomain_prefix | string | Yes | Subdomain prefix (e.g. mail, relay, ops). |
Response (201 Created)#
JSON
{ "domain": { "id": "2b3c4d5e-6f7a-8b9c-0d1e-2f3a4b5c6d7e", "domain": "mail.company.com", "parent_domain_id": "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d", "type": "custom", "is_active": false, "is_verified": false }}Configure Catch-All Routing#
PATCH /v1/custom-domains/:id
Enables or disables catch-all routing for a custom domain and configures fallback destination inbox and daily volume limits.
Scope:
domains:writeRate Limit: 60 req/minRequest Body Schema#
| Field | Type | Required | Description |
|---|---|---|---|
catch_all_enabled | boolean | Optional | Set true to route unassigned inbound emails. |
catch_all_destination_id | string | null | Optional | UUID of verified destination inbox for catch-all emails. |
catch_all_daily_limit | integer | Optional | Daily catch-all message limit (min 0, max 1000). |
Response (200 OK)#
JSON
{ "success": true, "domain": { "id": "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d", "domain": "company.com", "catch_all_enabled": true, "catch_all_destination_id": "8b7c6d5e-4f3a-2b1c-0d9e-8f7a6b5c4d3e" }}Verify DNS Records#
POST /v1/custom-domains/:id/verify-dns
Triggers live DNS verification across global resolvers, evaluating MX, SPF, DKIM, and DMARC records.
Scope:
domains:writeRate Limit: 60 req/minResponse (200 OK)#
JSON
{ "allVerified": true, "mx": { "valid": true, "details": "MX record verified" }, "spf": { "valid": true, "details": "SPF record verified" }, "dkim": { "valid": true, "details": "DKIM record verified" }, "dmarc": { "valid": true, "details": "DMARC record verified" }}Delete Custom Domain#
DELETE /v1/custom-domains/:id
Deletes a custom domain and releases all associated DNS routing tables. Deletion is blocked if any active aliases are linked to the domain.
Scope:
domains:writeRate Limit: 60 req/minIdempotent: YesError Responses#
| Status Code | Code | Error Message | Reason |
|---|---|---|---|
400 | ALIASES_EXIST | "Cannot delete domain with active aliases. Please reassign or delete them first." | The domain has active aliases. Response includes count and aliases array. |
404 | NOT_FOUND | "Domain not found" | Domain ID does not exist on your account. |