beehiiv Developer Documentation

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.

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Path parameters

publicationIdstringRequiredformat: "^(pub_[0-9a-fA-F\-]+)$"

The prefixed ID of the publication object

Request

This endpoint expects an object.

namestringRequired

The name of the newsletter list.

descriptionstringOptional

A description of the newsletter list.

slugstringOptional

A unique slug for the newsletter list. Auto-generated from the name if not provided.

auto_subscribebooleanOptional

Whether new subscribers are automatically subscribed to this list.

Response

Created

dataobject

Errors

400

Bad Request Error

401

Unauthorized Error

404

Not Found Error

422

Unprocessable Entity Error

429

Too Many Requests Error

500

Internal Server Error

$	curl -X POST https://api.beehiiv.com/v2/publications/pub_00000000-0000-0000-0000-000000000000/newsletter_lists \
>	-H "Authorization: Bearer <token>" \
>	-H "Content-Type: application/json" \
>	-d '{
>	"name": "Weekly Digest",
>	"description": "A weekly digest of the best content.",
>	"slug": "weekly-digest",
>	"auto_subscribe": false
>	}'

1	{
2	"data": {
3	"id": "nl_list_00000000-0000-0000-0000-000000000000",
4	"name": "Weekly Digest",
5	"slug": "weekly-digest",
6	"status": "active",
7	"auto_subscribe": false,
8	"subscriber_count": 100,
9	"created_at": 1672531200,
10	"updated_at": 1672531200,
11	"description": "A weekly digest of the best content."
12	}
13	}