Alias API - Anon.li Docs

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

Quick generation is handled by POST /api/v1/alias?generate=true, which keeps Bitwarden-style generation in the main alias route.

Endpoints

Generate Random Alias (Bitwarden)

Quickly generate a random alias. This is the primary Bitwarden-compatible flow for random alias creation.

POSThttps://anon.li/api/v1/alias?generate=true

Body Parameters

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

Example Request

Code

curl -X POST 'https://anon.li/api/v1/alias?generate=true' \
  -H "Authorization: Bearer ak_..." \
  -H "Content-Type: application/json" \
  -d '{}'

Response (201 Created)

Code

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

List Aliases

Retrieve all your active and inactive aliases.

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

Example Request

Code

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

Response

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

Create Alias

Create a new email alias that forwards to your inbox.

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

Body Parameters

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.

Alias labels and notes are vault-encrypted. Plaintext metadata fields (description, label, and note) are not accepted by the API. Create the alias first, then update encrypted_label or encrypted_note with ciphertext produced by a compatible vault client.

Example Request (Custom Alias)

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

Example Request (Random Alias)

Code

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

Response (201 Created)

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

Get Alias

Retrieve a single alias by ID.

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

Example Request

Code

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

Response

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

Update Alias

Update an existing alias. You can toggle the active status, update vault-encrypted metadata, or change which recipient inbox the alias forwards to.

PATCHhttps://anon.li/api/v1/alias/:id

Body Parameters

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.

The encrypted metadata envelope is versioned JSON: {"v":1,"alg":"AES-256-GCM","iv":"...","ct":"..."}. Encrypt labels and notes with the caller's unwrapped vault key and AES-GCM additional data anon.li:alias-metadata:v1:<aliasId>:label or anon.li:alias-metadata:v1:<aliasId>:note. Plaintext description, label, and note updates return 400.

Example Request (disable alias)

Code

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

Example Request (change forwarding destination)

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

Tip: The recipient must already be verified before you can assign it to an alias. See the Recipient API to add and verify recipients, or refer to the common workflow for a step-by-step guide.

Response

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

Delete Alias

Permanently delete an alias.

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

Example Request

Code

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

Response (200 OK)

Code

{
  "success": true
}

Error Responses

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

Rate Limits

API-key requests count against the monthly API request quota for your subscription plan. Dashboard actions do not consume this quota.

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

Rate limit headers are included in responses:

Code

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 950
X-RateLimit-Reset: 1699999999999

When you exceed your rate limit, the API returns a 429 Too Many Requests response.

CLI Usage

You can use the Alias API directly from the command line:

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

Authentication

Base URL

Bitwarden Integration

Endpoints

Generate Random Alias (Bitwarden)

List Aliases

Create Alias

Get Alias

Update Alias

Delete Alias

Error Responses

Rate Limits

CLI Usage

On this page