Domains API

Register and verify custom domains, configure CNAME-managed DKIM routing, inspect DNS propagation health, and query shared platform domains.

Quick Reference

DNS Requirements

To activate inbound routing and outbound email signing, publish the following DNS records with your DNS provider:

GET /v1/domains — List Available Domains

Scope: domains:read · Rate Limit: 60/min · Idempotent: Yes

Returns all active domains available for alias creation on your workspace, including verified custom domains and shared platform domains.

Example Request

curl -X GET "https://api.aliasfleet.com/v1/domains" \
  -H "Authorization: Bearer afp_4a8f9c1b2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e" \
  -H "Accept: application/json"

Response (200 OK)

{
  "domains": [
    {
      "id": "dom_bXm9kLpQr2nVwYz3",
      "domain": "mail.acme-corp.com",
      "type": "custom",
      "is_premium": false,
      "is_default": true
    },
    {
      "id": "dom_1a2b3c4d5e6f7g8h",
      "domain": "af-mail.com",
      "type": "shared",
      "is_premium": false,
      "is_default": false
    }
  ],
  "default_domain": {
    "id": "dom_bXm9kLpQr2nVwYz3",
    "domain": "mail.acme-corp.com",
    "type": "custom",
    "is_premium": false,
    "is_default": true
  }
}

GET /v1/custom-domains — List Custom Domains

Scope: domains:read · Rate Limit: 60/min · Idempotent: Yes

Returns the full hierarchy of custom domains and subdomains registered to your workspace, including per-record DNS health flags, catch-all rules, and active alias counts.

Example Request

curl -X GET "https://api.aliasfleet.com/v1/custom-domains" \
  -H "Authorization: Bearer afp_4a8f9c1b2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e" \
  -H "Accept: application/json"

Response (200 OK)

{
  "domains": [
    {
      "id": "dom_bXm9kLpQr2nVwYz3",
      "domain": "acme-corp.com",
      "type": "custom",
      "status": "active",
      "is_active": true,
      "mx_verified": true,
      "spf_verified": true,
      "dkim_verified": true,
      "dmarc_verified": true,
      "dns_health": "healthy",
      "dns_verified_at": "2026-08-10T14:22:00.000Z",
      "catch_all_enabled": true,
      "catch_all_destination_id": "dest_adn6UTmkzn6OWpGq",
      "alias_count": 42,
      "subdomains": [
        {
          "id": "dom_7f8g9h0i1j2k3l4m",
          "domain": "mail.acme-corp.com",
          "type": "custom",
          "status": "active",
          "is_active": true,
          "mx_verified": true,
          "spf_verified": true,
          "dns_health": "healthy",
          "parent_domain_id": "dom_bXm9kLpQr2nVwYz3",
          "alias_count": 18
        }
      ],
      "created_at": "2026-08-01T10:00:00.000Z"
    }
  ]
}

POST /v1/custom-domains — Register Custom Domain

Scope: domains:write · Rate Limit: 60/min · Idempotent: Yes

Registers a new apex domain or subdomain under your account. Prepares managed Dual-CNAME DKIM record targets and generates a 32-byte DNS verification token.

Request Body Parameters

Example Request

curl -X POST "https://api.aliasfleet.com/v1/custom-domains" \
  -H "Authorization: Bearer afp_4a8f9c1b2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "acme-corp.com"
  }'

Response (201 Created)

{
  "success": true,
  "domain": {
    "id": "dom_bXm9kLpQr2nVwYz3",
    "domain": "acme-corp.com",
    "type": "custom",
    "verification_token": "a1b2c3d4e5f67890abcdef1234567890abcdef1234567890abcdef1234567890",
    "status": "pending",
    "is_active": false,
    "category": "custom",
    "parent_domain_id": null,
    "catch_all_enabled": false,
    "created_at": "2026-09-04T12:00:00.000Z"
  },
  "verificationToken": "a1b2c3d4e5f67890abcdef1234567890abcdef1234567890abcdef1234567890"
}

Errors

GET /v1/custom-domains/:id/dns-records — Inspect Required DNS Records

Scope: domains:read · Rate Limit: 60/min · Idempotent: Yes

Retrieves the exact DNS records and target values required to activate a specific registered domain.

Path Parameters

Example Request

curl -X GET "https://api.aliasfleet.com/v1/custom-domains/dom_bXm9kLpQr2nVwYz3/dns-records" \
  -H "Authorization: Bearer afp_4a8f9c1b2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e" \
  -H "Accept: application/json"

Response (200 OK)

{
  "domain": "acme-corp.com",
  "is_cloudflare": false,
  "records": [
    {
      "type": "MX",
      "name": "@",
      "value": "relay.aliasfleet.com.",
      "priority": 10,
      "status": "pending",
      "required": true
    },
    {
      "type": "TXT",
      "name": "@",
      "value": "v=spf1 include:_spf.aliasfleet.com ~all",
      "status": "pending",
      "required": true
    },
    {
      "type": "CNAME",
      "name": "af1._domainkey",
      "value": "af1._domainkey._dkim.aliasfleet.com.",
      "status": "pending",
      "required": true
    },
    {
      "type": "CNAME",
      "name": "af2._domainkey",
      "value": "af2._domainkey._dkim.aliasfleet.com.",
      "status": "pending",
      "required": true
    },
    {
      "type": "TXT",
      "name": "_dmarc",
      "value": "v=DMARC1; p=none;",
      "status": "pending",
      "required": false
    }
  ]
}

POST /v1/custom-domains/:id/verify-dns — Verify DNS & Activate

Scope: domains:write · Rate Limit: 60/min · Idempotent: Yes

Queries authoritative global DNS resolvers in real time to validate published records. Once MX and SPF records resolve correctly, the domain activates immediately for incoming email routing.

Path Parameters

Example Request

curl -X POST "https://api.aliasfleet.com/v1/custom-domains/dom_bXm9kLpQr2nVwYz3/verify-dns" \
  -H "Authorization: Bearer afp_4a8f9c1b2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e"

Response: Fully Verified (200 OK)

{
  "success": true,
  "domain": "mail.acme-corp.com",
  "allVerified": true,
  "health": "healthy",
  "records": {
    "mx": {
      "valid": true,
      "verified": true,
      "value": "10 relay.aliasfleet.com",
      "details": "MX record verified"
    },
    "spf": {
      "valid": true,
      "verified": true,
      "value": "v=spf1 include:_spf.aliasfleet.com ~all",
      "details": "SPF record verified"
    },
    "dkim": {
      "valid": true,
      "verified": true,
      "details": "DKIM CNAME verified"
    },
    "dmarc": {
      "valid": true,
      "verified": true,
      "details": "DMARC policy detected"
    }
  }
}

Response: Records Incomplete (200 OK)

{
  "success": false,
  "domain": "mail.acme-corp.com",
  "allVerified": false,
  "health": "critical",
  "records": {
    "mx": {
      "valid": false,
      "verified": false,
      "details": "No MX records found pointing to relay.aliasfleet.com"
    },
    "spf": {
      "valid": false,
      "verified": false,
      "details": "Missing SPF mechanism: include:_spf.aliasfleet.com"
    }
  }
}

Errors

DELETE /v1/custom-domains/:id — Delete Custom Domain

Scope: domains:write · Rate Limit: 60/min · Idempotent: Yes

Permanently removes a custom domain from your workspace and releases associated routing records.

Path Parameters

Example Request

curl -X DELETE "https://api.aliasfleet.com/v1/custom-domains/dom_bXm9kLpQr2nVwYz3" \
  -H "Authorization: Bearer afp_4a8f9c1b2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e"

Response (200 OK)

{
  "success": true
}

Errors