> For the complete documentation index, see [llms.txt](https://api.senderwiz.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://api.senderwiz.com/customer/contact-list/create-a-list.md).

# Create a List

Create a new subscriber list by submitting general details, optional sender defaults, notification preferences information. Required fields must be included for a successful request.

### ➕ Create a List

Create a new subscriber list under your SenderWiz account.

#### 🔹 HTTP Request

```http
POST API-URL/lists
```

#### 🔸 Authorization Header

Include your customer API key:

```
X-API-KEY: your-api-key-here
```

#### 📝 POST Parameters

| Parameter | Type  | Required | Description                                                                               |
| --------- | ----- | -------- | ----------------------------------------------------------------------------------------- |
| `data`    | array | Yes      | Array containing list details. Accepts `general`, `defaults`, and `notifications` blocks. |

***

#### 📦 `general` Block *(Required)*

| Parameter     | Type   | Required | Description       |
| ------------- | ------ | -------- | ----------------- |
| `name`        | string | Yes      | Name of the list. |
| `description` | string | No       | List description  |

***

#### 📦 `defaults` Block *(Optional)*

| Parameter    | Type   | Required | Description             |
| ------------ | ------ | -------- | ----------------------- |
| `from_name`  | string | Yes      | Sender's name.          |
| `from_email` | string | Yes      | Sender's email address. |
| `reply_to`   | string | Yes      | Reply-to email address. |
| `subject`    | string | No       | Default subject line.   |

***

#### 📦 `notifications` Block *(Optional)*

| Parameter        | Type   | Required | Description                                         |
| ---------------- | ------ | -------- | --------------------------------------------------- |
| `subscribe`      | Yes/No | No       | Notify on new subscriber (yes or no).               |
| `unsubscribe`    | Yes/No | No       | Notify on unsubscribe (yes or no).                  |
| `subscribe_to`   | string | No       | Email address to receive subscribe notifications.   |
| `unsubscribe_to` | string | No       | Email address to receive unsubscribe notifications. |

***

#### 💻 PHP Example

```php
// create a new list
$response = $endpoint->create([
    // required
    'general' => [
        'name'          => 'API Test List', // required
        'description'   => 'This is a test list, created from the API.', // optional
    ],
    // optional
    'defaults' => [
        'from_name' => 'Emily Carter', // required
        'from_email'=> 'emily.carter@example.org', // required
        'reply_to'  => 'emily.carter@example.org', // required
        'subject'   => 'Welcome to Our Newsletter!', // required
    ],
    // optional
    'notifications' => [
        // notification when new subscriber added
        'subscribe'         => 'yes', // yes|no
        // notification when subscriber unsubscribes
        'unsubscribe'       => 'yes', // yes|no
        // where to send the notifications.
        'subscribe_to'      => 'emily.carter@example.org',
        'unsubscribe_to'    => 'emily.carter@example.org',
    ],
]);

// and get the response
echo '<pre>';
print_r($response->body);
echo '</pre>';

```

#### 📦 Sample JSON Response

```json
{
  "status": "success",
  "list_uid": "lm451q7h7j3e2"
}
```

***