# Delete a list

Source: https://docs.emelia.io/docs/lists/delete-list

Guide: [Lists & contacts](https://docs.emelia.io/docs/lists.md)

`DELETE https://api.emelia.io/lists/list/{listId}`

Permanently deletes the list, every contact and company row it contains, and its child or linked lists. The deleted list and its contacts are removed from the recipients of your campaigns, which are then resynchronized: deleting a list used as an exclusion list puts the contacts it was excluding back into the campaigns. This cannot be undone.

The call is synchronous: deleting a very large list can take a while.

## Authentication

Send your API key in the `Authorization` header: `Authorization: <your API key>`.

## Path parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `listId` | string | yes | List id. |

## Example request

**cURL**

```bash
curl -X DELETE "https://api.emelia.io/lists/list/65f1a2b3c4d5e6f760f68df4" \
  -H "Authorization: $EMELIA_API_KEY"
```

**JavaScript**

```js
const response = await fetch('https://api.emelia.io/lists/list/65f1a2b3c4d5e6f760f68df4', {
  method: 'DELETE',
  headers: { Authorization: process.env.EMELIA_API_KEY },
});
console.log(await response.json());
```

**Python**

```python
import os
import requests

response = requests.delete(
    "https://api.emelia.io/lists/list/65f1a2b3c4d5e6f760f68df4",
    headers={"Authorization": os.environ["EMELIA_API_KEY"]},
)
print(response.json())
```

## Responses

### 200: List deleted, with deletion counters.

| Field | Type | Required | Description |
|---|---|---|---|
| `success` | boolean | yes |  |
| `deletedLists` | integer | yes | The list plus its linked lists. |
| `deletedContacts` | integer | yes |  |
| `deletedCompanies` | integer | yes |  |
| `campaignsUpdated` | integer | yes | Campaigns whose recipients were updated. |

```json
{
  "success": true,
  "deletedLists": 1,
  "deletedContacts": 42,
  "deletedCompanies": 40,
  "campaignsUpdated": 1
}
```

### 400: The list id is not a valid ObjectId.

| Field | Type | Required | Description |
|---|---|---|---|
| `message` | string | yes | English, human-readable message. |
| `code` | string | no | Stable error code, when available (for example `PAYLOAD_TOO_LARGE`, `INVALID_JSON`, `export_too_large`, `companies_only`, `enrichment_running`). |
| `params` | object | no |  |
| `error` | string | no | Raw internal message (unexpected errors only). |

```json
{
  "message": "Invalid list id"
}
```

### 401: Missing, unknown or disabled API key, or the account of the key no longer exists. Note the body shape: `error` and `code`, not `message`.

| Field | Type | Required | Description |
|---|---|---|---|
| `error` | string | yes |  |
| `code` | enum: `AUTH_REQUIRED`, `ACCOUNT_NOT_FOUND` | yes |  |

```json
{
  "error": "string",
  "code": "AUTH_REQUIRED"
}
```

### 404: The list does not exist or belongs to another account.

| Field | Type | Required | Description |
|---|---|---|---|
| `message` | string | yes | English, human-readable message. |
| `code` | string | no | Stable error code, when available (for example `PAYLOAD_TOO_LARGE`, `INVALID_JSON`, `export_too_large`, `companies_only`, `enrichment_running`). |
| `params` | object | no |  |
| `error` | string | no | Raw internal message (unexpected errors only). |

```json
{
  "message": "List not found"
}
```

### 500: Unexpected server error. `error`, when present, is a raw internal message: do not parse it. Retry later.

| Field | Type | Required | Description |
|---|---|---|---|
| `message` | string | yes | English, human-readable message. |
| `code` | string | no | Stable error code, when available (for example `PAYLOAD_TOO_LARGE`, `INVALID_JSON`, `export_too_large`, `companies_only`, `enrichment_running`). |
| `params` | object | no |  |
| `error` | string | no | Raw internal message (unexpected errors only). |

```json
{
  "message": "Hmm... Something went wrong. Please try again later."
}
```