Domain API - Docs

The Domain API allows you to add custom domains to your anon.li account and verify their DNS configuration. Once verified, you can create aliases using your own domain instead of @anon.li.

Authentication

All API requests must be authenticated using an API Key. Generate keys in your Dashboard.

Code

Authorization: Bearer ak_your_api_key_here

Base URL

Code

https://anon.li/api/v1

Endpoints

List Domains

Retrieve all custom domains for your account.

GEThttps://anon.li/api/v1/domain

Example Request

Code

curl https://anon.li/api/v1/domain \
  -H "Authorization: Bearer ak_..."

Response

Code

{
  "data": [
    {
      "id": "domain_xyz123",
      "domain": "mail.example.com",
      "verified": true,
      "ownership_verified": true,
      "mx_verified": true,
      "spf_verified": true,
      "dkim_verified": true,
      "verification_token": "3f9c2a7e51b04d8c96e1a0b7d2c4f68e9a1b3c5d7e9f0a2b",
      "dkim_public_key": "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkq...\n-----END PUBLIC KEY-----\n",
      "dkim_selector": "default",
      "created_at": "2026-01-15T10:00:00.000Z"
    }
  ],
  "meta": {
    "request_id": "req_abc123",
    "total": 1,
    "limit": 1,
    "offset": 0,
    "has_more": false
  }
}

Add Domain

Add a new custom domain to your account. A DKIM key pair is generated automatically, so the response already includes dkim_public_key and dkim_selector. Custom domains require a Plus or Pro plan; adding a domain beyond your plan's limit returns 403.

POSThttps://anon.li/api/v1/domain

Body Parameters

Field	Type	Required	Description
`domain`	string	Yes	Domain name in lowercase (e.g., `mail.example.com`). Must match `^[a-z0-9.-]+\.[a-z]{2,}$`.

Example Request

Code

curl -X POST https://anon.li/api/v1/domain \
  -H "Authorization: Bearer ak_..." \
  -H "Content-Type: application/json" \
  -d '{"domain": "mail.example.com"}'

Response (201)

Code

{
  "data": {
    "id": "domain_xyz123",
    "domain": "mail.example.com",
    "verified": false,
    "ownership_verified": false,
    "mx_verified": false,
    "spf_verified": false,
    "dkim_verified": false,
    "verification_token": "3f9c2a7e51b04d8c96e1a0b7d2c4f68e9a1b3c5d7e9f0a2b",
    "dkim_public_key": "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkq...\n-----END PUBLIC KEY-----\n",
    "dkim_selector": "default",
    "created_at": "2026-01-15T10:00:00.000Z"
  },
  "meta": {
    "request_id": "req_abc123"
  }
}

Get Domain Details

Retrieve a domain with its DNS configuration records.

GEThttps://anon.li/api/v1/domain/:id

Example Request

Code

curl https://anon.li/api/v1/domain/domain_xyz123 \
  -H "Authorization: Bearer ak_..."

Response

The response includes the full domain object plus a dns_records object listing every DNS record required for verification, including the DKIM record.

Code

{
  "data": {
    "id": "domain_xyz123",
    "domain": "mail.example.com",
    "verified": false,
    "ownership_verified": false,
    "mx_verified": false,
    "spf_verified": false,
    "dkim_verified": false,
    "verification_token": "3f9c2a7e51b04d8c96e1a0b7d2c4f68e9a1b3c5d7e9f0a2b",
    "dkim_public_key": "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkq...\n-----END PUBLIC KEY-----\n",
    "dkim_selector": "default",
    "created_at": "2026-01-15T10:00:00.000Z",
    "dns_records": {
      "ownership": {
        "type": "TXT",
        "host": "mail.example.com",
        "value": "anon.li=3f9c2a7e51b04d8c96e1a0b7d2c4f68e9a1b3c5d7e9f0a2b"
      },
      "mx": {
        "type": "MX",
        "host": "mail.example.com",
        "value": "mx.anon.li",
        "priority": 10
      },
      "spf": {
        "type": "TXT",
        "host": "mail.example.com",
        "value": "v=spf1 include:anon.li ~all"
      },
      "dkim": {
        "type": "TXT",
        "host": "default._domainkey.mail.example.com",
        "value": "v=DKIM1; k=rsa; p=MIIBIjANBgkq..."
      }
    }
  },
  "meta": {
    "request_id": "req_abc123"
  }
}

Verify Domain

Check DNS records and update the domain's verification status. A domain is verified only when the ownership TXT, MX, SPF, and DKIM records all resolve correctly. dns_verified reports whether the mail-routing records (MX, SPF, DKIM) are correct, independent of ownership.

POSThttps://anon.li/api/v1/domain/:id/verify

Example Request

Code

curl -X POST https://anon.li/api/v1/domain/domain_xyz123/verify \
  -H "Authorization: Bearer ak_..." \
  -H "Content-Type: application/json" \
  -d '{}'

Response

Code

{
  "data": {
    "verified": true,
    "ownership_verified": true,
    "mx_verified": true,
    "spf_verified": true,
    "dkim_verified": true,
    "dns_verified": true
  },
  "meta": {
    "request_id": "req_abc123"
  }
}

Regenerate DKIM Key

Generate a new DKIM key pair for a domain and return the new DKIM DNS record.

POSThttps://anon.li/api/v1/domain/:id/dkim

This replaces your existing DKIM key

Regenerating invalidates the DKIM TXT record currently published in your DNS and resets dkim_verified to false. Because DKIM is required for verification, the domain will not pass verification again until you publish the new record and call the verify endpoint. To read the current DKIM record without rotating it, use GET /api/v1/domain/:id (dns_records.dkim).

Example Request

Code

curl -X POST https://anon.li/api/v1/domain/domain_xyz123/dkim \
  -H "Authorization: Bearer ak_..."

Response

Code

{
  "data": {
    "id": "domain_xyz123",
    "domain": "mail.example.com",
    "dkim_selector": "default",
    "dkim_record": {
      "type": "TXT",
      "host": "default._domainkey.mail.example.com",
      "value": "v=DKIM1; k=rsa; p=MIIBIjANBgkq..."
    }
  },
  "meta": {
    "request_id": "req_abc123"
  }
}

Delete Domain

Permanently remove a domain from your account. Aliases using this domain will no longer receive email.

DELETEhttps://anon.li/api/v1/domain/:id

Example Request

Code

curl -X DELETE https://anon.li/api/v1/domain/domain_xyz123 \
  -H "Authorization: Bearer ak_..."

Response

Code

{
  "data": {
    "deleted": true
  },
  "meta": {
    "request_id": "req_abc123"
  }
}

Domain Object

Field	Type	Description
`id`	string	Unique domain identifier
`domain`	string	The domain name
`verified`	boolean	Ownership, MX, SPF, and DKIM records all verified
`ownership_verified`	boolean	TXT ownership record verified
`mx_verified`	boolean	MX record verified
`spf_verified`	boolean	SPF record verified
`dkim_verified`	boolean	DKIM record verified
`verification_token`	string	Token for ownership TXT record
`dkim_public_key`	string \| null	DKIM public key (PEM). Generated automatically when the domain is added
`dkim_selector`	string \| null	DKIM selector (`default`)
`created_at`	string	ISO 8601 creation timestamp

Verification Workflow

Add your domain - POST /api/v1/domain
Get DNS records - GET /api/v1/domain/:id to see the required ownership TXT, MX, SPF, and DKIM records in dns_records
Configure DNS - Add all four records to your DNS provider. DKIM is required: a domain without a valid DKIM record does not verify
Verify - POST /api/v1/domain/:id/verify to check your configuration

Only call POST /api/v1/domain/:id/dkim if you need to rotate the DKIM key; it replaces the published key and you must update DNS and verify again.

DNS propagation

DNS changes can take up to 48 hours to propagate. If verification fails, wait a few hours and try again.

Error Responses

Status	Code	Description
`400`	`VALIDATION_ERROR`	Invalid domain format, or a reserved domain (`anon.li` and its subdomains)
`401`	`UNAUTHORIZED`	Invalid or missing API key
`402`	`PAYMENT_REQUIRED`	Team workspace without an active Business plan
`403`	`FORBIDDEN`	Custom domains not included in your plan, or domain limit reached
`404`	`NOT_FOUND`	Domain not found
`409`	`CONFLICT`	Domain already added to your account, or already verified by another account
`429`	`RATE_LIMITED`	Too many requests

Authentication

Base URL

Endpoints

List Domains

Add Domain

Get Domain Details

Verify Domain

Regenerate DKIM Key

Delete Domain

Domain Object

Verification Workflow

Error Responses

On this page