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

# List newsletter lists <Badge intent="info" minimal outlined>OAuth Scope: newsletter_lists:read</Badge>

GET https://api.beehiiv.com/v2/publications/{publicationId}/newsletter_lists

List all newsletter lists for a publication.

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

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

### Query parameters

- `limit` (integer, optional) — A limit on the number of objects to be returned. The limit can range between 1 and 100, and the default is 10.
- `page` (integer, optional) — Pagination returns the results in pages. Each page contains the number of results specified by the `limit` (default: 10).If not specified, results 1-10 from page 1 will be returned.
- `direction` (enum, optional, default: asc) — The direction that the results are sorted in. Defaults to asc `asc` - Ascending, sorts from smallest to largest. `desc` - Descending, sorts from largest to smallest.
  - Allowed values: `asc`, `desc`

## Response

### 200

OK

- `data` (list of NewsletterListInfo, required)
- `limit` (integer, required) — The limit placed on the results. If no limit was specified in the request, this defaults to 10.
- `page` (integer, required, default: 1) — The page number the results are from. If no page was specified in the request, this defaults to page 1.
- `total_results` (integer, required) — The total number of results from all pages.
- `total_pages` (integer, required) — The total number of pages.

## 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)

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

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

**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
    }
  ],
  "limit": 10,
  "page": 1,
  "total_results": 1,
  "total_pages": 1
}
```

**SDK Code**

```python
import requests

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

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, 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: 'GET', headers: {Authorization: 'Bearer <token>'}};

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"
	"net/http"
	"io"
)

func main() {

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

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	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::Get.new(url)
request["Authorization"] = 'Bearer <token>'

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.get("https://api.beehiiv.com/v2/publications/pub_00000000-0000-0000-0000-000000000000/newsletter_lists")
  .header("Authorization", "Bearer <token>")
  .asString();
```

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

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.beehiiv.com/v2/publications/pub_00000000-0000-0000-0000-000000000000/newsletter_lists', [
  'headers' => [
    'Authorization' => 'Bearer <token>',
  ],
]);

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.GET);
request.AddHeader("Authorization", "Bearer <token>");
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = ["Authorization": "Bearer <token>"]

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 = "GET"
request.allHTTPHeaderFields = headers

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()
```