beehiiv Developer Documentation

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,
  "show_in_preference_center": true
}'

{
  "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
  }
}

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.

show_in_preference_centerbooleanOptional

Whether the list appears on the subscriber Manage Preferences page, where subscribers can opt in to or out of it. Defaults to false.

email_settingsobjectOptional

The sending identity for posts sent to this list. Any field omitted is inherited from the publication.

headersmap from strings to optional stringsOptional

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_sourcestringOptional

The utm_source appended to links in posts sent to this list.

utm_mediumstringOptional

The utm_medium appended to links in posts sent to this list.

utm_campaignstringOptional

The utm_campaign appended to links in posts sent to this list.

utm_params_enabledbooleanOptional

Whether UTM parameters are appended to links in posts sent to this list. Omit to inherit from the publication.

tier_idslist of stringsOptional

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

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