List Mailing Lists
curl --request GET \
--url https://api.example.com/email/listsimport requests
url = "https://api.example.com/email/lists"
response = requests.get(url)
print(response.text)const options = {method: 'GET'};
fetch('https://api.example.com/email/lists', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.example.com/email/lists",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.example.com/email/lists"
req, _ := http.NewRequest("GET", url, nil)
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.example.com/email/lists")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/email/lists")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
response = http.request(request)
puts response.read_body{
"id": "<string>",
"name": "<string>",
"recipient_count": 123,
"active_count": 123,
"removed_count": 123,
"unsubscribed_count": 123,
"created_at": "<string>"
}Mailing Lists
List Mailing Lists
List the mailing lists of your API token’s project
GET
/
email
/
lists
List Mailing Lists
curl --request GET \
--url https://api.example.com/email/listsimport requests
url = "https://api.example.com/email/lists"
response = requests.get(url)
print(response.text)const options = {method: 'GET'};
fetch('https://api.example.com/email/lists', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.example.com/email/lists",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.example.com/email/lists"
req, _ := http.NewRequest("GET", url, nil)
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.example.com/email/lists")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/email/lists")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
response = http.request(request)
puts response.read_body{
"id": "<string>",
"name": "<string>",
"recipient_count": 123,
"active_count": 123,
"removed_count": 123,
"unsubscribed_count": 123,
"created_at": "<string>"
}Returns an array of the mailing lists belonging to the project your API token is scoped to, with recipient counts by status. Use the returned
API tokens are created in the Dashboard under API Keys.
id values with Upsert Recipients and the other recipient endpoints, or create a list with Create Mailing List.
Authentication
This endpoint requires an API token passed as a Bearer token in theAuthorization header.
Authorization: Bearer YOUR_API_TOKEN
Request
curl -X GET "https://api.shipstar.ai/api/v1/email/lists" \
-H "Authorization: Bearer YOUR_API_TOKEN"
const response = await fetch('https://api.shipstar.ai/api/v1/email/lists', {
headers: {
'Authorization': 'Bearer YOUR_API_TOKEN'
}
});
const lists = await response.json();
import requests
response = requests.get(
'https://api.shipstar.ai/api/v1/email/lists',
headers={'Authorization': 'Bearer YOUR_API_TOKEN'}
)
lists = response.json()
Response
Returns an array of mailing list objects.string
required
The mailing list’s unique identifier (UUID)
string
required
The mailing list’s name
integer
required
Total number of recipients on the list in every status
integer
required
Recipients who will receive the next release email
integer
required
Recipients you removed (an upsert or add reactivates them)
integer
required
Recipients who unsubscribed themselves (never reactivated by the API)
string
required
When the list was created (ISO 8601 timestamp)
Example Response
200
[
{
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"name": "Release announcements",
"recipient_count": 240,
"active_count": 232,
"removed_count": 3,
"unsubscribed_count": 5,
"created_at": "2026-06-15T09:30:00Z"
}
]
Errors
| Status | Description |
|---|---|
| 401 | Invalid or expired API token |
Rate Limits
This endpoint is limited to 100 requests per minute per IP.Was this page helpful?