> 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.

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

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

Update a newsletter list belonging to a specific publication.

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

## 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
- `newsletterListId` (string, required) — The prefixed ID of the newsletter list object

### Body (application/json)

This endpoint expects an object.

- `name` (string, optional) — 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_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. Archived lists cannot be shown; archiving a list hides it.
- `status` (enum, optional) — The status of the newsletter list. Valid values are `active` and `archived`. Setting `draft` is not permitted.
  - Allowed values: `active`, `archived`
- `email_settings` (NewsletterListEmailSettings, optional) — The sending identity for posts sent to this list. Only the provided fields within this object will be updated.
- `headers` (map from string to string, optional) — Custom email headers for posts sent to this list. When provided, this replaces all existing headers on the 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. Headers SendGrid reserves, such as From, Reply-To and Subject, are rejected.
- `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. When left unset on the list, falls back to the publication.
- `tier_ids` (list of string, optional) — The prefixed IDs of the paid tiers that gate this list. When provided, this replaces the list's gating tiers. Pass an empty array to open the list to everyone, and omit it or pass null to leave the tiers unchanged. 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

### 200

OK

- `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 Updated",
  "status": "active"
}
```

**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/nl_list_00000000-0000-0000-0000-000000000000"

payload = {
    "name": "Weekly Digest Updated",
    "status": "active"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.patch(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/nl_list_00000000-0000-0000-0000-000000000000';
const options = {
  method: 'PATCH',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"name":"Weekly Digest Updated","status":"active"}'
};

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/nl_list_00000000-0000-0000-0000-000000000000"

	payload := strings.NewReader("{\n  \"name\": \"Weekly Digest Updated\",\n  \"status\": \"active\"\n}")

	req, _ := http.NewRequest("PATCH", 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/nl_list_00000000-0000-0000-0000-000000000000")

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

request = Net::HTTP::Patch.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"Weekly Digest Updated\",\n  \"status\": \"active\"\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.patch("https://api.beehiiv.com/v2/publications/pub_00000000-0000-0000-0000-000000000000/newsletter_lists/nl_list_00000000-0000-0000-0000-000000000000")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"Weekly Digest Updated\",\n  \"status\": \"active\"\n}")
  .asString();
```

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

$client = new \GuzzleHttp\Client();

$response = $client->request('PATCH', 'https://api.beehiiv.com/v2/publications/pub_00000000-0000-0000-0000-000000000000/newsletter_lists/nl_list_00000000-0000-0000-0000-000000000000', [
  'body' => '{
  "name": "Weekly Digest Updated",
  "status": "active"
}',
  '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/nl_list_00000000-0000-0000-0000-000000000000");
var request = new RestRequest(Method.PATCH);
request.AddHeader("Authorization", "Bearer <token>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"name\": \"Weekly Digest Updated\",\n  \"status\": \"active\"\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 Updated",
  "status": "active"
] 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/nl_list_00000000-0000-0000-0000-000000000000")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "PATCH"
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()
```