List Contacts
curl --request GET \
--url https://api.example.com/api/v1/contact-lists/{listId}/contactsimport requests
url = "https://api.example.com/api/v1/contact-lists/{listId}/contacts"
response = requests.get(url)
print(response.text)const options = {method: 'GET'};
fetch('https://api.example.com/api/v1/contact-lists/{listId}/contacts', 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/api/v1/contact-lists/{listId}/contacts",
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/api/v1/contact-lists/{listId}/contacts"
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/api/v1/contact-lists/{listId}/contacts")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/api/v1/contact-lists/{listId}/contacts")
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{
"data": [
{
"id": "<string>",
"email": "<string>",
"firstName": "<string>",
"lastName": "<string>",
"phoneNumber": "<string>",
"customFields": {},
"status": "<string>",
"source": "<string>",
"createdAt": "<string>",
"updatedAt": "<string>",
"consentType": "<string>",
"consentSource": "<string>",
"consentTimestamp": "<string>",
"consentIpAddress": "<string>"
}
],
"pagination": {
"page": 123,
"limit": 123,
"total": 123,
"totalPages": 123
}
}Contacts
List Contacts
Retrieve paginated list of contacts
GET
/
api
/
v1
/
contact-lists
/
{listId}
/
contacts
List Contacts
curl --request GET \
--url https://api.example.com/api/v1/contact-lists/{listId}/contactsimport requests
url = "https://api.example.com/api/v1/contact-lists/{listId}/contacts"
response = requests.get(url)
print(response.text)const options = {method: 'GET'};
fetch('https://api.example.com/api/v1/contact-lists/{listId}/contacts', 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/api/v1/contact-lists/{listId}/contacts",
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/api/v1/contact-lists/{listId}/contacts"
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/api/v1/contact-lists/{listId}/contacts")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/api/v1/contact-lists/{listId}/contacts")
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{
"data": [
{
"id": "<string>",
"email": "<string>",
"firstName": "<string>",
"lastName": "<string>",
"phoneNumber": "<string>",
"customFields": {},
"status": "<string>",
"source": "<string>",
"createdAt": "<string>",
"updatedAt": "<string>",
"consentType": "<string>",
"consentSource": "<string>",
"consentTimestamp": "<string>",
"consentIpAddress": "<string>"
}
],
"pagination": {
"page": 123,
"limit": 123,
"total": 123,
"totalPages": 123
}
}List all contacts in a list with optional filtering by status.
Path Parameters
string
required
The unique list ID (e.g.,
lst_abc123).Query Parameters
integer
default:"1"
Page number for pagination.
integer
default:"20"
Number of items per page (max 100).
string
Filter by contact status:
active, unsubscribed, bounced, complained, or suppressed.Examples
import { MailBreeze } from "mailbreeze";
const mailbreeze = new MailBreeze({ apiKey: "sk_live_xxx" });
const contacts = mailbreeze.contacts("lst_abc123");
// List all contacts
const { data, pagination } = await contacts.list();
console.log(`Found ${pagination.total} contacts`);
// List with status filter
const { data } = await contacts.list({
status: "active",
page: 1,
limit: 50,
});
for (const contact of data) {
console.log(`${contact.email}: ${contact.firstName} ${contact.lastName}`);
}
from mailbreeze import MailBreeze
client = MailBreeze(api_key="sk_live_xxx")
contacts = client.contacts("lst_abc123")
# List all contacts
result = await contacts.list()
print(f"Found {result.pagination.total} contacts")
# List with status filter
result = await contacts.list(
status="active",
page=1,
limit=50,
)
for contact in result.data:
print(f"{contact.email}: {contact.first_name} {contact.last_name}")
client := mailbreeze.NewClient("sk_live_xxx")
contacts := client.Contacts("lst_abc123")
// List all contacts
result, err := contacts.List(ctx, nil)
if err != nil {
log.Fatal(err)
}
fmt.Printf("Found %d contacts\n", result.Pagination.Total)
// List with status filter
result, err := contacts.List(ctx, &mailbreeze.ListContactsParams{
Status: "active",
Page: 1,
Limit: 50,
})
for _, contact := range result.Data {
fmt.Printf("%s: %s %s\n", contact.Email, contact.FirstName, contact.LastName)
}
$mailbreeze = new MailBreeze('sk_live_xxx');
// List all contacts
$response = $mailbreeze->contacts->list('lst_abc123');
$result = $response['data'];
echo "Found " . $result['pagination']['total'] . " contacts\n";
// List with status filter
$response = $mailbreeze->contacts->list('lst_abc123', [
'status' => 'active',
'page' => 1,
'limit' => 50,
]);
$result = $response['data'];
foreach ($result['contacts'] as $contact) {
echo $contact['email'] . ": " . $contact['firstName'] . " " . $contact['lastName'] . "\n";
}
let client = Client::new("sk_live_xxx");
let contacts = client.contacts("lst_abc123");
// List all contacts
let result = contacts.list(None).await?;
println!("Found {} contacts", result.pagination.total);
// List with status filter
let result = contacts.list(Some(ListContactsParams {
status: Some("active".to_string()),
page: Some(1),
limit: Some(50),
})).await?;
for contact in result.data {
println!("{}: {} {}", contact.email, contact.first_name.unwrap_or_default(), contact.last_name.unwrap_or_default());
}
# List all contacts
curl "https://api.mailbreeze.com/api/v1/contact-lists/694fc1669e63563857ae8d72/contacts" \
-H "Authorization: Bearer sk_live_xxx"
# List with status filter
curl "https://api.mailbreeze.com/api/v1/contact-lists/694fc1669e63563857ae8d72/contacts?status=active&page=1&limit=50" \
-H "Authorization: Bearer sk_live_xxx"
Response
array
Array of contact objects.
Show Contact object
Show Contact object
string
Unique contact ID.
string
Contact’s email address.
string
Contact’s first name.
string
Contact’s last name.
string
Contact’s phone number.
object
Custom field values.
string
Contact status:
active, unsubscribed, bounced, complained, or suppressed.string
Acquisition source.
string
ISO 8601 timestamp when created.
string
ISO 8601 timestamp when last updated.
string
Type of consent:
explicit, implicit, or legitimate_interest.string
Where consent was collected.
string
ISO 8601 timestamp when consent was given.
string
IP address from which consent was given.
object
Example Response
{
"success": true,
"data": {
"contacts": [
{
"id": "8f1701be-0d2a-4519-999c-0574a3d68668",
"domainId": "6911cf4253eb3ff3b4de6215",
"contactListId": "694fc1669e63563857ae8d72",
"email": "user@example.com",
"firstName": "John",
"lastName": "Doe",
"customFields": {},
"status": "active",
"source": "console",
"subscriptionToken": "b839501cb01ca878a01bd2d8d947ad3350b53afbf5370d3b3e1999c958ce309a",
"createdAt": "2025-12-27T12:36:25.458Z",
"updatedAt": "2025-12-27T12:36:26.851Z"
}
],
"contactListCustomFields": {},
"pagination": {
"page": 1,
"limit": 20,
"total": 100141,
"totalPages": 5008
}
},
"meta": {
"timestamp": "2025-12-27T13:40:36.952Z",
"requestId": "94718148-9068-497e-86d8-69b42030d011",
"path": "/api/v1/contact-lists/694fc1669e63563857ae8d72/contacts"
}
}