# Kiteworks API — externalDL Operations
**3 endpoints** | [Browse interactive reference](https://developer.kiteworks.com/api-reference/externalDL.html) | [Download spec slice](https://developer.kiteworks.com/assets/specs/externalDL.json)
> **Authentication required.** All requests must include a Bearer access token in the
> `Authorization` header. See [Authentication](https://developer.kiteworks.com/authentication.md) for how to
> obtain a token using OAuth 2.0 Authorization Code (PKCE) or JWT Bearer flow.
---
## GET /rest/externalDL
**Summary:** List external distribution lists
### Description:
Returns the list of external distribution lists for the current user.
### Precondition:
User must be authenticated.
### Response:
The list of external distribution lists is returned.
**Parameters:**
| Name | In | Required | Description |
|------|----|----------|-------------|
| `search` | query | no | Search term to filter external distribution lists by email address. |
**Responses:**
| Code | Description |
|------|-------------|
| 200 | The external distribution lists have been successfully returned. |
| 401 | Unauthorized Possible error codes: ERR_ACCESS_USER, ERR_AUTH_INVALID_CSRF, ERR_AUTH_UNAUTHORIZED |
| 403 | Forbidden Possible error codes: ERR_ACCESS_DENIED |
| 490 | Request blocked by WAF |
**Response Examples:**
**401 (ERR_ACCESS_USER):**
```json
{
"errors": [
{
"code": "ERR_ACCESS_USER",
"message": "Insufficient access permissions"
}
]
}
```
**401 (ERR_AUTH_INVALID_CSRF):**
```json
{
"errors": [
{
"code": "ERR_AUTH_INVALID_CSRF",
"message": "Invalid CSRF Authentication"
}
]
}
```
**401 (ERR_AUTH_UNAUTHORIZED):**
```json
{
"errors": [
{
"code": "ERR_AUTH_UNAUTHORIZED",
"message": "Unauthorized"
}
]
}
```
**403 (ERR_ACCESS_DENIED):**
```json
{
"errors": [
{
"code": "ERR_ACCESS_DENIED",
"message": "Your access is denied.",
"redirectUrl": "/login?code=3317"
}
]
}
```
**Code Samples:**
**cURL:**
```shell
curl -X GET \
"https://{instance}.kiteworks.com/rest/externalDL" \
-H "Authorization: Bearer YOUR_TOKEN"
```
**Python:**
```python
import requests
url = "https://{instance}.kiteworks.com/rest/externalDL"
headers = {
"Authorization": "Bearer YOUR_TOKEN",
}
response = requests.get(url, headers=headers)
print(response.json())
```
---
## POST /rest/externalDL
**Summary:** Add external distribution lists
### Description:
Adds one or more email addresses to the current user's external distribution lists.
### Precondition:
User must be authenticated.
### Response:
The external distribution lists are created and returned.
**Request Body:**
| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `emails` | string[] | yes | List of email addresses to add or remove from the external distribution lists. |
**Responses:**
| Code | Description |
|------|-------------|
| 201 | The external distribution lists have been successfully added. |
| 401 | Unauthorized Possible error codes: ERR_ACCESS_USER, ERR_AUTH_INVALID_CSRF, ERR_AUTH_UNAUTHORIZED |
| 403 | Forbidden Possible error codes: ERR_ACCESS_DENIED |
| 490 | Request blocked by WAF |
**Response Examples:**
**401 (ERR_ACCESS_USER):**
```json
{
"errors": [
{
"code": "ERR_ACCESS_USER",
"message": "Insufficient access permissions"
}
]
}
```
**401 (ERR_AUTH_INVALID_CSRF):**
```json
{
"errors": [
{
"code": "ERR_AUTH_INVALID_CSRF",
"message": "Invalid CSRF Authentication"
}
]
}
```
**401 (ERR_AUTH_UNAUTHORIZED):**
```json
{
"errors": [
{
"code": "ERR_AUTH_UNAUTHORIZED",
"message": "Unauthorized"
}
]
}
```
**403 (ERR_ACCESS_DENIED):**
```json
{
"errors": [
{
"code": "ERR_ACCESS_DENIED",
"message": "Your access is denied.",
"redirectUrl": "/login?code=3317"
}
]
}
```
**Code Samples:**
**cURL:**
```shell
curl -X POST \
"https://{instance}.kiteworks.com/rest/externalDL" \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"emails": [
"string"
]
}'
```
**Python:**
```python
import requests
url = "https://{instance}.kiteworks.com/rest/externalDL"
headers = {
"Authorization": "Bearer YOUR_TOKEN",
"Content-Type": "application/json",
}
payload = {
"emails": [
"string"
]
}
response = requests.post(url, headers=headers, json=payload)
print(response.json())
```
---
## DELETE /rest/externalDL
**Summary:** Delete external distribution lists
### Description:
Removes one or more email addresses from the current user's external distribution lists.
### Precondition:
User must be authenticated.
### Response:
The specified external distribution lists are deleted.
**Request Body:**
| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `emails` | string[] | yes | List of email addresses to add or remove from the external distribution lists. |
**Responses:**
| Code | Description |
|------|-------------|
| 200 | The external distribution lists have been successfully deleted. |
| 401 | Unauthorized Possible error codes: ERR_ACCESS_USER, ERR_AUTH_INVALID_CSRF, ERR_AUTH_UNAUTHORIZED |
| 403 | Forbidden Possible error codes: ERR_ACCESS_DENIED |
| 490 | Request blocked by WAF |
**Response Examples:**
**401 (ERR_ACCESS_USER):**
```json
{
"errors": [
{
"code": "ERR_ACCESS_USER",
"message": "Insufficient access permissions"
}
]
}
```
**401 (ERR_AUTH_INVALID_CSRF):**
```json
{
"errors": [
{
"code": "ERR_AUTH_INVALID_CSRF",
"message": "Invalid CSRF Authentication"
}
]
}
```
**401 (ERR_AUTH_UNAUTHORIZED):**
```json
{
"errors": [
{
"code": "ERR_AUTH_UNAUTHORIZED",
"message": "Unauthorized"
}
]
}
```
**403 (ERR_ACCESS_DENIED):**
```json
{
"errors": [
{
"code": "ERR_ACCESS_DENIED",
"message": "Your access is denied.",
"redirectUrl": "/login?code=3317"
}
]
}
```
**Code Samples:**
**cURL:**
```shell
curl -X DELETE \
"https://{instance}.kiteworks.com/rest/externalDL" \
-H "Authorization: Bearer YOUR_TOKEN"
```
**Python:**
```python
import requests
url = "https://{instance}.kiteworks.com/rest/externalDL"
headers = {
"Authorization": "Bearer YOUR_TOKEN",
}
response = requests.delete(url, headers=headers)
print(response.json())
```
---