> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developers.beehiiv.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.beehiiv.com/_mcp/server.

# Create newsletter list <Badge intent="info" minimal outlined>OAuth Scope: newsletter_lists:write</Badge>

POST https://api.beehiiv.com/v2/publications/{publicationId}/newsletter_lists
Content-Type: application/json

Create a new newsletter list for a publication. The list will be created with an active status. The slug will be auto-generated from the name if not provided.

Reference: https://developers.beehiiv.com/api-reference/newsletter-lists/create

## Authentication

- `Authorization` header (bearer token, required) — Bearer authentication of the form `Bearer <token>`, where token is your auth token.

## Request

### Path parameters

- `publicationId` (string, required) — The prefixed ID of the publication object

### Body (application/json)

This endpoint expects an object.

- `name` (string, required) — The name of the newsletter list.
- `description` (string, optional) — A description of the newsletter list.
- `slug` (string, optional) — A unique slug for the newsletter list. Auto-generated from the name if not provided.
- `auto_subscribe` (boolean, optional) — Whether new subscribers are automatically subscribed to this list.
- `show_in_preference_center` (boolean, optional) — Whether the list appears on the subscriber Manage Preferences page, where subscribers can opt in to or out of it. Defaults to `false`.
- `email_settings` (NewsletterListEmailSettings, optional) — The sending identity for posts sent to this list. Any field omitted is inherited from the publication.
- `headers` (map from string to string, optional) — Custom email headers for posts sent to this list. Merges with publication headers at send time, with this list's values winning on a key collision. Set a value to `null` to suppress a header inherited from the publication. System-managed headers (e.g. List-Unsubscribe, X-SMTPAPI) cannot be overridden.
- `utm_source` (string, optional) — The utm_source appended to links in posts sent to this list.
- `utm_medium` (string, optional) — The utm_medium appended to links in posts sent to this list.
- `utm_campaign` (string, optional) — The utm_campaign appended to links in posts sent to this list.
- `utm_params_enabled` (boolean, optional) — Whether UTM parameters are appended to links in posts sent to this list. Omit to inherit from the publication.
- `tier_ids` (list of string, optional) — The prefixed IDs of the paid tiers that gate this list. Only subscribers on one of these tiers can see and join the list from the Manage Preferences page. Each tier must belong to the publication. Tier gating is in beta and this field is ignored until it has been enabled for the publication.

## Response

### 201

Created

- `data` (NewsletterListInfo, required)

## Errors

### 400 Bad Request Error

Bad Request

- `status` (integer, required)
- `statusText` (string, required)
- `errors` (list of ErrorDetail, required)

### 401 Unauthorized Error

Unauthorized. The API key or OAuth access token is missing, invalid, or expired.

- `status` (integer, required)
- `statusText` (string, required)
- `errors` (list of ErrorDetail, required)

### 404 Not Found Error

Resource Not Found

- `status` (integer, required)
- `statusText` (string, required)
- `errors` (list of ErrorDetail, required)

### 422 Unprocessable Entity Error

Unprocessable Entity

- `status` (integer, required)
- `statusText` (string, required)
- `errors` (list of ErrorDetail, required)

### 429 Too Many Requests Error

Rate Limit Exceeded

- `status` (integer, required)
- `statusText` (string, required)
- `errors` (list of ErrorDetail, required)

### 500 Internal Server Error

Internal Server Error

- `status` (integer, required)
- `statusText` (string, required)
- `errors` (list of ErrorDetail, required)

## Types

### NewsletterListEmailSettings

Sending identity for posts sent to this list. Each field falls back to the publication when left unset.

- `from_address` (string, optional) — Email address to send from. Must be an existing from address owned by the publication. Returns 422 if not found.
- `reply_to_address` (string, optional) — Email address to set as Reply-To. Must be a verified reply-to address owned by the publication. Returns 422 if not found.
- `sender_name` (string, optional) — The sender name preset, expressed as a composition key: either a single token, or `<token>|<connector>|<token>`. Tokens are `brand`, `list`, `authors_first` and `authors_full`; connectors are `from`, `with`, `by`, `at`, `comma`, `colon` and `space`. For the list Weekly Digest on the publication Bee Informed, `list|by|brand` renders as "Weekly Digest by Bee Informed". Pass `null` to clear the override and inherit from the publication.

### NewsletterListInfo

- `id` (string, required) — The prefixed ID of the newsletter list.
- `name` (string, required) — The name of the newsletter list.
- `slug` (string, required) — The URL-friendly slug of the newsletter list.
- `status` (enum, required) — The status of the newsletter list.
  - Allowed values: `draft`, `active`, `archived`
- `auto_subscribe` (boolean, required) — Whether new subscribers are automatically subscribed to this list.
- `show_in_preference_center` (boolean, required) — Whether the list appears on the subscriber Manage Preferences page, where subscribers can opt in to or out of it.
- `subscriber_count` (integer, required) — The number of active subscribers on this list.
- `created_at` (integer, required) — The time the newsletter list was created. Measured in seconds since the Unix epoch.
- `updated_at` (integer, required) — The time the newsletter list was last updated. Measured in seconds since the Unix epoch.
- `tier_ids` (list of string, required) — The prefixed IDs of the paid tiers that gate this list. Only subscribers on one of these tiers can see and join the list from the Manage Preferences page. Empty when the list is open to everyone. Tier gating is in beta and is only applied for publications where it has been enabled.
- `description` (string, optional) — A description of the newsletter list.
- `from_address` (string, optional) — The from address for posts sent to this list. If not set, falls back to the publication default.
- `reply_to_address` (string, optional) — The reply-to address for posts sent to this list. If not set, falls back to the publication default.
- `sender_name` (string, optional) — The sender name preset composition key set on this list. If not set, falls back to the publication.
- `headers` (map from string to string, optional) — Custom email headers set on this list. A `null` value is a suppression marker for a header inherited from the publication.
- `utm_source` (string, optional) — The utm_source appended to links in posts sent to this list.
- `utm_medium` (string, optional) — The utm_medium appended to links in posts sent to this list.
- `utm_campaign` (string, optional) — The utm_campaign appended to links in posts sent to this list.
- `utm_params_enabled` (boolean, optional) — Whether UTM parameters are appended to links in posts sent to this list. If not set, falls back to the publication.

### ErrorDetail

- `message` (string, required)
- `code` (string, required)

## Examples

**Request**

```json
{
  "name": "Weekly Digest",
  "description": "A weekly digest of the best content.",
  "slug": "weekly-digest",
  "auto_subscribe": false,
  "show_in_preference_center": true
}
```

**Response**

```json
{
  "data": {
    "id": "nl_list_00000000-0000-0000-0000-000000000000",
    "name": "Weekly Digest",
    "slug": "weekly-digest",
    "status": "active",
    "auto_subscribe": false,
    "show_in_preference_center": true,
    "subscriber_count": 100,
    "created_at": 1672531200,
    "updated_at": 1672531200,
    "tier_ids": [
      "tier_00000000-0000-0000-0000-000000000000"
    ],
    "description": "A weekly digest of the best content.",
    "from_address": "digest@mail.example.com",
    "reply_to_address": "replies@example.com",
    "sender_name": "list|by|brand",
    "headers": {
      "X-Campaign-Id": "weekly-digest"
    },
    "utm_source": "newsletter",
    "utm_medium": "email",
    "utm_campaign": "weekly-digest",
    "utm_params_enabled": true
  }
}
```

**SDK Code**

```python
import requests

url = "https://api.beehiiv.com/v2/publications/pub_00000000-0000-0000-0000-000000000000/newsletter_lists"

payload = {
    "name": "Weekly Digest",
    "description": "A weekly digest of the best content.",
    "slug": "weekly-digest",
    "auto_subscribe": False,
    "show_in_preference_center": True
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript
const url = 'https://api.beehiiv.com/v2/publications/pub_00000000-0000-0000-0000-000000000000/newsletter_lists';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"name":"Weekly Digest","description":"A weekly digest of the best content.","slug":"weekly-digest","auto_subscribe":false,"show_in_preference_center":true}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.beehiiv.com/v2/publications/pub_00000000-0000-0000-0000-000000000000/newsletter_lists"

	payload := strings.NewReader("{\n  \"name\": \"Weekly Digest\",\n  \"description\": \"A weekly digest of the best content.\",\n  \"slug\": \"weekly-digest\",\n  \"auto_subscribe\": false,\n  \"show_in_preference_center\": true\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.beehiiv.com/v2/publications/pub_00000000-0000-0000-0000-000000000000/newsletter_lists")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"Weekly Digest\",\n  \"description\": \"A weekly digest of the best content.\",\n  \"slug\": \"weekly-digest\",\n  \"auto_subscribe\": false,\n  \"show_in_preference_center\": true\n}"

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://api.beehiiv.com/v2/publications/pub_00000000-0000-0000-0000-000000000000/newsletter_lists")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"Weekly Digest\",\n  \"description\": \"A weekly digest of the best content.\",\n  \"slug\": \"weekly-digest\",\n  \"auto_subscribe\": false,\n  \"show_in_preference_center\": true\n}")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.beehiiv.com/v2/publications/pub_00000000-0000-0000-0000-000000000000/newsletter_lists', [
  'body' => '{
  "name": "Weekly Digest",
  "description": "A weekly digest of the best content.",
  "slug": "weekly-digest",
  "auto_subscribe": false,
  "show_in_preference_center": true
}',
  'headers' => [
    'Authorization' => 'Bearer <token>',
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://api.beehiiv.com/v2/publications/pub_00000000-0000-0000-0000-000000000000/newsletter_lists");
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "Bearer <token>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"name\": \"Weekly Digest\",\n  \"description\": \"A weekly digest of the best content.\",\n  \"slug\": \"weekly-digest\",\n  \"auto_subscribe\": false,\n  \"show_in_preference_center\": true\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "Authorization": "Bearer <token>",
  "Content-Type": "application/json"
]
let parameters = [
  "name": "Weekly Digest",
  "description": "A weekly digest of the best content.",
  "slug": "weekly-digest",
  "auto_subscribe": false,
  "show_in_preference_center": true
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.beehiiv.com/v2/publications/pub_00000000-0000-0000-0000-000000000000/newsletter_lists")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```