Alias API - Anon.li Docs | anon.li

Alias API

Create and manage email aliases programmatically using the Alias API.

The Alias API allows you to create and manage email aliases programmatically. Use it to generate unique forwarding addresses for your users or integrate email aliasing into your applications.

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

Bitwarden Integration

anon.li is compatible with Bitwarden's email alias generator. To configure:

Open Bitwarden Settings → Options → Username Generator
Select "Forwarded Email Alias" → "addy.io" (or custom service)
Enter your API key and set the API URL to https://anon.li/api/v1
Generate aliases directly from Bitwarden when creating new logins

Field	Type	Required	Description
`domain`	string	No	The domain for the alias (default: `anon.li`).

{
  "data": {
    "id": "cuid...",
    "email": "x7k9m2@anon.li",
    "active": true,
    "description": null,
    "label": null,
    "note": null,
    "encrypted_label": null,
    "encrypted_note": null,
    "metadata_version": 1,
    "created_at": "2026-01-23T10:00:00.000Z",
    "updated_at": "2026-01-23T10:00:00.000Z"
  }
}

Code

{
  "data": [
    {
      "id": "cuid...",
      "email": "alias@anon.li",
      "active": true,
      "description": null,
      "label": null,
      "note": null,
      "encrypted_label": "{\"v\":1,\"alg\":\"AES-256-GCM\",\"iv\":\"...\",\"ct\":\"...\"}",
      "encrypted_note": null,
      "metadata_version": 1,
      "created_at": "2026-10-27T10:00:00.000Z",
      "updated_at": "2026-10-27T10:00:00.000Z"
    }
  ]
}

Field	Type	Required	Description
`local_part`	string	For custom	The part before the @ (e.g., `netflix` in `alias@anon.li`). Required when format is `custom`.
`domain`	string	No	The domain for the alias (default: `anon.li`).
`format`	string	No	Alias format: `random_characters`, `random_words`, `uuid`, or `custom`. Default: `random_characters`.
`recipient_ids`	string[]	No	Array of verified recipient IDs for multi-recipient routing. The first ID is primary. Limits are 1 on Free, 3 on Plus, and 5 on Pro.
`recipient_email`	string	No	Alternatively, specify a verified recipient by email address.

Code

curl -X POST https://anon.li/api/v1/alias \
  -H "Authorization: Bearer ak_..." \
  -H "Content-Type: application/json" \
  -d '{
    "local_part": "amazon",
    "domain": "anon.li",
    "format": "custom"
  }'

Code

{
  "data": {
    "id": "cuid...",
    "email": "amazon@anon.li",
    "active": true,
    "description": null,
    "label": null,
    "note": null,
    "encrypted_label": null,
    "encrypted_note": null,
    "metadata_version": 1,
    "created_at": "2026-10-27T10:05:00.000Z",
    "updated_at": "2026-10-27T10:05:00.000Z"
  }
}

Code

{
  "data": {
    "id": "cuid...",
    "email": "alias@anon.li",
    "active": true,
    "description": null,
    "label": null,
    "note": null,
    "encrypted_label": "{\"v\":1,\"alg\":\"AES-256-GCM\",\"iv\":\"...\",\"ct\":\"...\"}",
    "encrypted_note": null,
    "metadata_version": 1,
    "created_at": "2026-10-27T10:00:00.000Z",
    "updated_at": "2026-10-27T10:00:00.000Z"
  }
}

Field	Type	Required	Description
`active`	boolean	No	Enable or disable the alias.
`encrypted_label`	string \| null	No	Vault-encrypted alias label envelope. Send `null` to clear it.
`encrypted_note`	string \| null	No	Vault-encrypted alias note envelope. Send `null` to clear it.
`recipient_id`	string	No	Change the forwarding destination by recipient ID. The recipient must be verified.
`recipient_ids`	string[]	No	Replace the full recipient list for multi-recipient routing. The first ID is primary.
`recipient_email`	string	No	Change the forwarding destination by verified recipient email address.

Code

# Change which inbox this alias forwards to using a recipient ID
curl -X PATCH https://anon.li/api/v1/alias/cuid... \
  -H "Authorization: Bearer ak_..." \
  -H "Content-Type: application/json" \
  -d '{ "recipient_id": "rec_def456" }'

# Or specify the recipient by email address
curl -X PATCH https://anon.li/api/v1/alias/cuid... \
  -H "Authorization: Bearer ak_..." \
  -H "Content-Type: application/json" \
  -d '{ "recipient_email": "work@company.com" }'

Code

{
  "data": {
    "id": "cuid...",
    "email": "alias@anon.li",
    "active": false,
    "description": null,
    "label": null,
    "note": null,
    "encrypted_label": "{\"v\":1,\"alg\":\"AES-256-GCM\",\"iv\":\"...\",\"ct\":\"...\"}",
    "encrypted_note": null,
    "metadata_version": 1,
    "created_at": "2026-10-27T10:00:00.000Z",
    "updated_at": "2026-10-27T11:00:00.000Z"
  }
}

Status	Description
`400`	Bad Request - Invalid parameters
`401`	Unauthorized - Invalid or missing API key
`403`	Forbidden - Plan limit reached or domain not allowed
`404`	Not Found - Alias doesn't exist
`409`	Conflict - Alias already exists
`429`	Too Many Requests - Rate limit exceeded
`500`	Internal Server Error

Plan	Monthly Requests
Free	500
Plus	25,000
Pro	100,000

Code

# Generate a random alias
curl -X POST 'https://anon.li/api/v1/alias?generate=true' \
  -H "Authorization: Bearer ak_your_key" \
  -H "Content-Type: application/json"

# Create a custom alias
curl -X POST https://anon.li/api/v1/alias \
  -H "Authorization: Bearer ak_your_key" \
  -H "Content-Type: application/json" \
  -d '{"local_part": "myalias", "format": "custom"}'

# List all aliases
curl https://anon.li/api/v1/alias \
  -H "Authorization: Bearer ak_your_key"

# Disable an alias
curl -X PATCH https://anon.li/api/v1/alias/ALIAS_ID \
  -H "Authorization: Bearer ak_your_key" \
  -H "Content-Type: application/json" \
  -d '{"active": false}'

# Change where an alias forwards to
curl -X PATCH https://anon.li/api/v1/alias/ALIAS_ID \
  -H "Authorization: Bearer ak_your_key" \
  -H "Content-Type: application/json" \
  -d '{"recipient_id": "RECIPIENT_ID"}'

Alias API

Authentication

Base URL

Bitwarden Integration

On this page

Endpoints

Generate Random Alias (Bitwarden)

List Aliases

Create Alias

Get Alias

Update Alias

Delete Alias

Error Responses

Rate Limits

CLI Usage