# Add items to a list

> **POST** `https://api.us.nylas.com/v3/lists/{list_id}/items`

Source: https://developer.nylas.com/docs/reference/api/lists/add-list-items/

Adds items to the specified list. Values are normalized (lowercased and trimmed) and validated against the list's
`type` — `domain` lists accept domain names, `tld` lists accept top-level domains, and `address` lists accept full
email addresses. Duplicate additions are silently ignored.

The response returns the updated List object with a refreshed `items_count`. You can submit up to 1000 items per
request, and each item value can be at most 500 characters. Values that exceed this length return a `400`.

**Authentication:** NYLAS_API_KEY

## Parameters

### Path parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `list_id` | string | Yes | The ID of the list whose items you want to manage. |

## Request body

Content-Type: application/json

- `items` (array) **(required)**

## Responses

### 200 - OK

- `request_id` (string) - ID of the request.
- `data` (object)
  - `id` (string) - Globally unique identifier for the list (UUID).
  - `name` (string) - A human-readable name for the list. 1–256 characters. Required on create.
  - `description` (string) - An optional description of the list's purpose.
  - `type` (string) - The kind of values the list holds and which rule condition fields it can be used with. Required on create and
immutable after creation. `domain` holds domain names (matched against `from.domain` or `recipient.domain`),
`tld` holds top-level domains (matched against `from.tld` or `recipient.tld`), and `address` holds full email
addresses (matched against `from.address` or `recipient.address`).
  - `items_count` (integer) - The number of items currently in the list. Read-only; maintained by the system.
  - `application_id` (string) - The ID of the application that owns the list. Read-only; derived from the authenticated API key.
  - `organization_id` (string) - The ID of the Nylas organization that owns the list. Read-only; derived from the authenticated API key.
  - `created_at` (integer) - When the list was created, in seconds using the Unix timestamp format.
  - `updated_at` (integer) - When the list was last updated, in seconds using the Unix timestamp format.

### 400 - Bad Request

- `request_id` (string) - The request ID.
- `error` (object) - The response error object.
  - `type` (string) - The error type.
  - `message` (string) - The error message.
  - `provider_error` (object) - The error from the provider.

### 401 - Unauthorized

- `request_id` (string) - The request ID.
- `error` (object) - The response error object.
  - `type` (string) - The error type.
  - `message` (string) - The error message.
  - `provider_error` (object) - The error from the provider.

### 404 - Not Found

- `request_id` (string) - The request ID.
- `error` (object) - The response error object.
  - `type` (string) - The error type.
  - `message` (string) - The error message.
  - `provider_error` (object) - The raw error from the provider, if available
    - `code` (string)
    - `message` (string)

### 429 - Rate Limit

- `request_id` (string) - The request ID.
- `error` (object) - The response error object.
  - `type` (string) - The error type.
  - `message` (string) - The error message.

## Code samples

### cURL

```bash
curl -X POST "https://api.us.nylas.com/v3/lists/<LIST_ID>/items" \
  -H "Authorization: Bearer <NYLAS_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "items": ["spam-domain.com", "another-bad-domain.net"]
  }'

```

### Node.js SDK

```javascript
import Nylas from "nylas";

const nylas = new Nylas({
  apiKey: "<NYLAS_API_KEY>",
  apiUri: "<NYLAS_API_URI>",
});

async function addItems() {
  try {
    const list = await nylas.lists.addItems({
      listId: "<LIST_ID>",
      requestBody: {
        items: ["spam-domain.com", "another-bad-domain.net"],
      },
    });

    console.log("Updated list:", list);
  } catch (error) {
    console.error("Error adding items:", error);
  }
}

addItems();

```

### Python SDK

```python
from nylas import Client

nylas = Client(
    "<NYLAS_API_KEY>",
    "<NYLAS_API_URI>",
)

nylas_list = nylas.lists.add_items(
    list_id="<LIST_ID>",
    request_body={
        "items": ["spam-domain.com", "another-bad-domain.net"],
    },
)

print(nylas_list)

```