# Aliases API

> More addresses that deliver into one inbox. Every aliases endpoint with its scope, parameters, body and an example answer.

Source: https://docs.dissolve.email/reference/aliases

Base URL `https://api.dissolve.email`. Send an API key or OAuth access token as `Authorization: Bearer <token>` ([Authentication](/authentication)); an OAuth token needs the scope on each endpoint. Errors follow [one shape](/errors).

| Endpoint | Summary |
|---|---|
| `GET /v1/inboxes/{id}/aliases` | [List an inbox's aliases](#list-an-inbox-s-aliases) |
| `POST /v1/inboxes/{id}/aliases` | [Create an alias](#create-an-alias) |
| `DELETE /v1/inboxes/{id}/aliases/{aliasId}` | [Delete an alias](#delete-an-alias) |

### List an inbox's aliases

`GET /v1/inboxes/{id}/aliases` (scope `inboxes:read`)

Other addresses that deliver into this inbox, newest first.

**Path parameters**

| Name | Description |
|---|---|
| `id` | The aliase id. |

```bash cURL
curl "https://api.dissolve.email/v1/inboxes/$INBOX_ID/aliases" \
  -H "Authorization: Bearer $DISSOLVE_API_KEY"
```

```ts TypeScript
import { Dissolve } from '@dissolve-email/sdk';

const client = new Dissolve(); // reads DISSOLVE_API_KEY
const result = await client.v1.listAliases(inboxId);
```

```python Python
import os, requests

API_KEY = os.environ["DISSOLVE_API_KEY"]
response = requests.get(f"https://api.dissolve.email/v1/inboxes/{inbox_id}/aliases", headers={"Authorization": f"Bearer {API_KEY}"})
print(response.json())
```

**Response** `200`

```json
[
  {
    "id": "als6Rb1TnW8qXk3Zm5PcV",
    "aliasAddress": "billing@dissolve.email",
    "createdAt": "2026-11-19T10:01:00.000Z"
  }
]
```

### Create an alias

`POST /v1/inboxes/{id}/aliases` (scope `inboxes:write`)

Adds another address on the inbox's domain (Pro 5 per inbox, Business 25; owner only).

**Path parameters**

| Name | Description |
|---|---|
| `id` | The aliase id. |

**Body** (`application/json`)

| Name | Type | Required | Description |
|---|---|---|---|
| `alias` | string | yes | The local part: lower case letters, digits and inner hyphens. At most 50 characters. |

```bash cURL
curl -X POST "https://api.dissolve.email/v1/inboxes/$INBOX_ID/aliases" \
  -H "Authorization: Bearer $DISSOLVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"alias":"billing"}'
```

```ts TypeScript
import { Dissolve } from '@dissolve-email/sdk';

const client = new Dissolve(); // reads DISSOLVE_API_KEY
const result = await client.v1.createAlias(inboxId, {
  alias: "billing"
});
```

```python Python
import os, requests

API_KEY = os.environ["DISSOLVE_API_KEY"]
response = requests.post(f"https://api.dissolve.email/v1/inboxes/{inbox_id}/aliases", json={
  "alias": "billing"
}, headers={"Authorization": f"Bearer {API_KEY}"})
print(response.json())
```

**Response** `201`

```json
{
  "id": "als6Rb1TnW8qXk3Zm5PcV",
  "aliasAddress": "billing@dissolve.email",
  "inboxId": "V1StGXR8Z5jdHi6BmyT2k",
  "createdAt": "2026-11-19T10:01:00.000Z",
  "message": "Alias billing@dissolve.email created. Mail to it lands in this inbox."
}
```

### Delete an alias

`DELETE /v1/inboxes/{id}/aliases/{aliasId}` (scope `inboxes:write`)

Removes the alias. Its address is held back for a while before anyone else can take it.

**Path parameters**

| Name | Description |
|---|---|
| `id` | The aliase id. |
| `aliasId` | The alias id. |

```bash cURL
curl -X DELETE "https://api.dissolve.email/v1/inboxes/$INBOX_ID/aliases/$ALIAS_ID" \
  -H "Authorization: Bearer $DISSOLVE_API_KEY"
```

```ts TypeScript
import { Dissolve } from '@dissolve-email/sdk';

const client = new Dissolve(); // reads DISSOLVE_API_KEY
const result = await client.v1.deleteAlias(inboxId, aliasId);
```

```python Python
import os, requests

API_KEY = os.environ["DISSOLVE_API_KEY"]
response = requests.delete(f"https://api.dissolve.email/v1/inboxes/{inbox_id}/aliases/{alias_id}", headers={"Authorization": f"Bearer {API_KEY}"})
print(response.json())
```

**Response** `200`

```json
{
  "success": true,
  "message": "Alias billing@dissolve.email deleted."
}
```
