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

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

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

Retrieve a single newsletter list belonging to a specific publication.

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

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

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

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

**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"

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

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

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/nl_list_00000000-0000-0000-0000-000000000000")
  .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/nl_list_00000000-0000-0000-0000-000000000000', [
  '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/nl_list_00000000-0000-0000-0000-000000000000");
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/nl_list_00000000-0000-0000-0000-000000000000")! 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()
```