---
title: "Create a list"
method: POST
path: "/v3/lists"
tags: ["Lists"]
---

# Create a list

`POST /v3/lists`

Creates a list for your application. Lists are typed collections of values (domains, TLDs, or email addresses)
that can be referenced by rules using the `in_list` condition operator.

The list's `type` is set at creation and cannot be changed.

## Request body

- object
  - `name` string, required
  - `description` string
  - `type` 'domain' | 'tld' | 'address', required — The kind of values the list holds. Immutable after creation.

## Response `201`

Created

- object
  - `request_id` string — ID of the request.
  - `data` ListObject
    - `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` 'domain' | 'tld' | 'address' — 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.

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `429` — Rate Limit

---

[API](https://skmtc.dev/nylas/apis/nylas-api.md) · [All operations](https://skmtc.dev/nylas/apis/nylas-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/nylas/nylas-api/revisions/51c2c1b4ecff/schema)