Get Mailing List
curl --request GET \
--url https://api.example.com/email/lists/{list_id}import requests
url = "https://api.example.com/email/lists/{list_id}"
response = requests.get(url)
print(response.text)const options = {method: 'GET'};
fetch('https://api.example.com/email/lists/{list_id}', 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/{list_id}",
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/{list_id}"
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/{list_id}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/email/lists/{list_id}")
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
Get Mailing List
One mailing list with recipient counts by status
GET
/
email
/
lists
/
{list_id}
Get Mailing List
curl --request GET \
--url https://api.example.com/email/lists/{list_id}import requests
url = "https://api.example.com/email/lists/{list_id}"
response = requests.get(url)
print(response.text)const options = {method: 'GET'};
fetch('https://api.example.com/email/lists/{list_id}', 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/{list_id}",
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/{list_id}"
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/{list_id}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/email/lists/{list_id}")
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 a single mailing list with its recipient counts — the quickest way to check that a sync landed (
active_count went up) without paging through recipients.
Authentication
This endpoint requires an API token passed as a Bearer token in theAuthorization header.
Authorization: Bearer YOUR_API_TOKEN
Path Parameters
string
required
The mailing list’s unique identifier (UUID).
Request
cURL
curl "https://api.shipstar.ai/api/v1/email/lists/a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
-H "Authorization: Bearer YOUR_API_TOKEN"
Response
string
required
The mailing list’s unique identifier (UUID)
string
required
The mailing list’s name
integer
required
Total recipients on the list, in every status
integer
required
Recipients who will receive the next release email (at most 500)
integer
required
Recipients you removed. An upsert or add reactivates them.
integer
required
Recipients who unsubscribed themselves. Never reactivated by the API.
string
required
ISO 8601 creation timestamp
200
{
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"name": "Product updates",
"recipient_count": 312,
"active_count": 298,
"removed_count": 9,
"unsubscribed_count": 5,
"created_at": "2026-07-10T09:12:00Z"
}
Errors
| Status | Description |
|---|---|
| 401 | Invalid or expired API token |
| 404 | Mailing list not found in the token’s project |
Rate Limits
This endpoint is limited to 100 requests per minute per IP.Was this page helpful?