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](/dashboard/api-keys). ```bash Authorization: Bearer ak_your_api_key_here ``` ## Base URL ``` https://anon.li/api/v1 ``` ## Bitwarden Integration anon.li is compatible with Bitwarden's email alias generator. To configure: 1. Open Bitwarden Settings → Options → Username Generator 2. Select "Forwarded Email Alias" → "addy.io" (or custom service) 3. Enter your API key and set the API URL to `https://anon.li/api/v1` 4. Generate aliases directly from Bitwarden when creating new logins The `/api/v1/alias/generate` endpoint is specifically designed for Bitwarden compatibility. --- ## Endpoints ### Generate Random Alias (Bitwarden) Quickly generate a random alias. This is the primary endpoint for Bitwarden integration.

POST https://anon.li/api/v1/alias/generate

**Body Parameters** | Field | Type | Required | Description | | :--- | :--- | :--- | :--- | | `domain` | string | No | The domain for the alias (default: `anon.li`). | **Example Request** ```bash curl -X POST https://anon.li/api/v1/alias/generate \ -H "Authorization: Bearer ak_..." \ -H "Content-Type: application/json" \ -d '{}' ``` **Response (201 Created)** ```json { "data": { "id": "cuid...", "email": "x7k9m2@anon.li", "active": true, "description": null, "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.

GET https://anon.li/api/v1/alias

**Example Request** ```bash curl https://anon.li/api/v1/alias \ -H "Authorization: Bearer ak_..." ``` **Response** ```json { "data": [ { "id": "cuid...", "email": "alias@anon.li", "active": true, "description": "Streaming service", "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.

POST https://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`. | | `description` | string | No | A note to remember what this alias is for. | **Example Request (Custom Alias)** ```bash 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", "description": "Shopping" }' ``` **Example Request (Random Alias)** ```bash 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)** ```json { "data": { "id": "cuid...", "email": "amazon@anon.li", "active": true, "description": "Shopping", "created_at": "2026-10-27T10:05:00.000Z", "updated_at": "2026-10-27T10:05:00.000Z" } } ``` --- ### Get Alias Retrieve a single alias by ID.

GET https://anon.li/api/v1/alias/:id

**Example Request** ```bash curl https://anon.li/api/v1/alias/cuid... \ -H "Authorization: Bearer ak_..." ``` **Response** ```json { "data": { "id": "cuid...", "email": "alias@anon.li", "active": true, "description": "Streaming", "created_at": "2026-10-27T10:00:00.000Z", "updated_at": "2026-10-27T10:00:00.000Z" } } ``` --- ### Update Alias Update an existing alias (toggle active status, change description).

PATCH https://anon.li/api/v1/alias/:id

**Body Parameters** | Field | Type | Required | Description | | :--- | :--- | :--- | :--- | | `active` | boolean | No | Enable or disable the alias. | | `description` | string | No | Update the description. | **Example Request** ```bash curl -X PATCH https://anon.li/api/v1/alias/cuid... \ -H "Authorization: Bearer ak_..." \ -H "Content-Type: application/json" \ -d '{ "active": false }' ``` **Response** ```json { "data": { "id": "cuid...", "email": "alias@anon.li", "active": false, "description": "Streaming", "created_at": "2026-10-27T10:00:00.000Z", "updated_at": "2026-10-27T11:00:00.000Z" } } ``` --- ### Delete Alias Permanently delete an alias.

DELETE https://anon.li/api/v1/alias/:id

**Example Request** ```bash curl -X DELETE https://anon.li/api/v1/alias/cuid... \ -H "Authorization: Bearer ak_..." ``` **Response (200 OK)** ```json { "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 request limits are based on your subscription plan: | Plan | Monthly Requests | | :--- | :--- | | Free | 500 | | Plus | 25,000 | | Pro | 100,000 | Rate limit headers are included in responses: ``` 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: ```bash # Generate a random alias curl -X POST https://anon.li/api/v1/alias/generate \ -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}' ```