Skip to content

Domain API

Add, verify, and manage custom domains for your email aliases using the Domain API.

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": "anon_abc123def456",
      "dkim_public_key": "MIIBIjANBgkq...",
      "dkim_selector": "default",
      "created_at": "2026-01-15T10:00:00.000Z"
    }
  ]
}

Add Domain

Add a new custom domain to your account.

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

Body Parameters

FieldTypeRequiredDescription
domainstringYesDomain 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": "anon_abc123def456",
    "dkim_public_key": null,
    "dkim_selector": null,
    "created_at": "2026-01-15T10:00:00.000Z"
  }
}

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 a dns_records object showing the required DNS records for verification.

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": "anon_abc123def456",
    "dns_records": {
      "ownership": {
        "type": "TXT",
        "host": "mail.example.com",
        "value": "anon.li=anon_abc123def456"
      },
      "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": null
    }
  }
}

Verify Domain

Check DNS records and update the domain's verification status.

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": false
  }
}

Get DKIM Records

Retrieve or generate DKIM key configuration for a domain.

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

Example Request

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

Response

Code
{
  "data": {
    "dkim_selector": "default",
    "dkim_record": {
      "type": "TXT",
      "host": "default._domainkey.mail.example.com",
      "value": "v=DKIM1; k=rsa; p=MIIBIjANBgkq..."
    }
  }
}

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
  }
}

Domain Object

FieldTypeDescription
idstringUnique domain identifier
domainstringThe domain name
verifiedbooleanAll DNS records verified
ownership_verifiedbooleanTXT ownership record verified
mx_verifiedbooleanMX record verified
spf_verifiedbooleanSPF record verified
dkim_verifiedbooleanDKIM record verified
verification_tokenstringToken for ownership TXT record
dkim_public_keystring | nullDKIM public key
dkim_selectorstring | nullDKIM selector
created_atstringISO 8601 creation timestamp

Verification Workflow

  1. Add your domain - POST /api/v1/domain
  2. Get DNS records - GET /api/v1/domain/:id to see the required TXT, MX, and SPF records
  3. Configure DNS - Add the records to your DNS provider
  4. Verify - POST /api/v1/domain/:id/verify to check your configuration
  5. Set up DKIM (optional) - GET /api/v1/domain/:id/dkim to get the DKIM TXT record, add it to DNS, then 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

StatusCodeDescription
400VALIDATION_ERRORInvalid domain format
401UNAUTHORIZEDInvalid or missing API key
404NOT_FOUNDDomain not found
409CONFLICTDomain already exists
429RATE_LIMITEDToo many requests