Create List
curl --request POST \
--url https://api.example.com/api/v1/contact-lists \
--header 'Content-Type: application/json' \
--data '
{
"name": "<string>",
"description": "<string>",
"customFields": [
{
"key": "<string>",
"label": "<string>",
"type": "<string>",
"required": true,
"defaultValue": "<any>",
"options": [
"<string>"
]
}
]
}
'import requests
url = "https://api.example.com/api/v1/contact-lists"
payload = {
"name": "<string>",
"description": "<string>",
"customFields": [
{
"key": "<string>",
"label": "<string>",
"type": "<string>",
"required": True,
"defaultValue": "<any>",
"options": ["<string>"]
}
]
}
headers = {"Content-Type": "application/json"}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify({
name: '<string>',
description: '<string>',
customFields: [
{
key: '<string>',
label: '<string>',
type: '<string>',
required: true,
defaultValue: '<any>',
options: ['<string>']
}
]
})
};
fetch('https://api.example.com/api/v1/contact-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/api/v1/contact-lists",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'name' => '<string>',
'description' => '<string>',
'customFields' => [
[
'key' => '<string>',
'label' => '<string>',
'type' => '<string>',
'required' => true,
'defaultValue' => '<any>',
'options' => [
'<string>'
]
]
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.example.com/api/v1/contact-lists"
payload := strings.NewReader("{\n \"name\": \"<string>\",\n \"description\": \"<string>\",\n \"customFields\": [\n {\n \"key\": \"<string>\",\n \"label\": \"<string>\",\n \"type\": \"<string>\",\n \"required\": true,\n \"defaultValue\": \"<any>\",\n \"options\": [\n \"<string>\"\n ]\n }\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.example.com/api/v1/contact-lists")
.header("Content-Type", "application/json")
.body("{\n \"name\": \"<string>\",\n \"description\": \"<string>\",\n \"customFields\": [\n {\n \"key\": \"<string>\",\n \"label\": \"<string>\",\n \"type\": \"<string>\",\n \"required\": true,\n \"defaultValue\": \"<any>\",\n \"options\": [\n \"<string>\"\n ]\n }\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/api/v1/contact-lists")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n \"name\": \"<string>\",\n \"description\": \"<string>\",\n \"customFields\": [\n {\n \"key\": \"<string>\",\n \"label\": \"<string>\",\n \"type\": \"<string>\",\n \"required\": true,\n \"defaultValue\": \"<any>\",\n \"options\": [\n \"<string>\"\n ]\n }\n ]\n}"
response = http.request(request)
puts response.read_body{
"id": "<string>",
"name": "<string>",
"description": "<string>",
"customFields": [
{}
],
"contactCount": 123,
"createdAt": "<string>",
"updatedAt": "<string>"
}Lists
Create List
Create a new contact list
POST
/
api
/
v1
/
contact-lists
Create List
curl --request POST \
--url https://api.example.com/api/v1/contact-lists \
--header 'Content-Type: application/json' \
--data '
{
"name": "<string>",
"description": "<string>",
"customFields": [
{
"key": "<string>",
"label": "<string>",
"type": "<string>",
"required": true,
"defaultValue": "<any>",
"options": [
"<string>"
]
}
]
}
'import requests
url = "https://api.example.com/api/v1/contact-lists"
payload = {
"name": "<string>",
"description": "<string>",
"customFields": [
{
"key": "<string>",
"label": "<string>",
"type": "<string>",
"required": True,
"defaultValue": "<any>",
"options": ["<string>"]
}
]
}
headers = {"Content-Type": "application/json"}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify({
name: '<string>',
description: '<string>',
customFields: [
{
key: '<string>',
label: '<string>',
type: '<string>',
required: true,
defaultValue: '<any>',
options: ['<string>']
}
]
})
};
fetch('https://api.example.com/api/v1/contact-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/api/v1/contact-lists",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'name' => '<string>',
'description' => '<string>',
'customFields' => [
[
'key' => '<string>',
'label' => '<string>',
'type' => '<string>',
'required' => true,
'defaultValue' => '<any>',
'options' => [
'<string>'
]
]
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.example.com/api/v1/contact-lists"
payload := strings.NewReader("{\n \"name\": \"<string>\",\n \"description\": \"<string>\",\n \"customFields\": [\n {\n \"key\": \"<string>\",\n \"label\": \"<string>\",\n \"type\": \"<string>\",\n \"required\": true,\n \"defaultValue\": \"<any>\",\n \"options\": [\n \"<string>\"\n ]\n }\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.example.com/api/v1/contact-lists")
.header("Content-Type", "application/json")
.body("{\n \"name\": \"<string>\",\n \"description\": \"<string>\",\n \"customFields\": [\n {\n \"key\": \"<string>\",\n \"label\": \"<string>\",\n \"type\": \"<string>\",\n \"required\": true,\n \"defaultValue\": \"<any>\",\n \"options\": [\n \"<string>\"\n ]\n }\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/api/v1/contact-lists")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n \"name\": \"<string>\",\n \"description\": \"<string>\",\n \"customFields\": [\n {\n \"key\": \"<string>\",\n \"label\": \"<string>\",\n \"type\": \"<string>\",\n \"required\": true,\n \"defaultValue\": \"<any>\",\n \"options\": [\n \"<string>\"\n ]\n }\n ]\n}"
response = http.request(request)
puts response.read_body{
"id": "<string>",
"name": "<string>",
"description": "<string>",
"customFields": [
{}
],
"contactCount": 123,
"createdAt": "<string>",
"updatedAt": "<string>"
}Create a new contact list for organizing email recipients with optional custom field definitions.
Request Body
List name (max 100 characters).
Optional description (max 500 characters).
Custom field definitions for contacts in this list.
Show Custom field object
Show Custom field object
Field key used in API (e.g.,
company, plan).Display label shown in UI.
Field type:
text, number, date, boolean, or select.Whether field is required when creating contacts.
Default value for the field.
Required for
select type. Array of valid options.Examples
import { MailBreeze } from "mailbreeze";
const mailbreeze = new MailBreeze({ apiKey: "sk_live_xxx" });
// Simple list
const list = await mailbreeze.lists.create({
name: "Newsletter Subscribers",
description: "Weekly newsletter recipients",
});
// List with custom fields
const list = await mailbreeze.lists.create({
name: "VIP Customers",
description: "High-value customers",
customFields: [
{ key: "company", label: "Company", type: "text" },
{ key: "revenue", label: "Annual Revenue", type: "number" },
{ key: "plan", label: "Plan", type: "select", options: ["free", "pro", "enterprise"] },
{ key: "signupDate", label: "Signup Date", type: "date" },
{ key: "isActive", label: "Active", type: "boolean", defaultValue: true },
],
});
console.log(list.id); // "lst_xxx"
from mailbreeze import MailBreeze
client = MailBreeze(api_key="sk_live_xxx")
# Simple list
list = await client.lists.create(
name="Newsletter Subscribers",
description="Weekly newsletter recipients",
)
# List with custom fields
list = await client.lists.create(
name="VIP Customers",
description="High-value customers",
custom_fields=[
{"key": "company", "label": "Company", "type": "text"},
{"key": "revenue", "label": "Annual Revenue", "type": "number"},
{"key": "plan", "label": "Plan", "type": "select", "options": ["free", "pro", "enterprise"]},
],
)
print(list.id) # "lst_xxx"
client := mailbreeze.NewClient("sk_live_xxx")
// Simple list
list, err := client.Lists.Create(ctx, &mailbreeze.CreateListParams{
Name: "Newsletter Subscribers",
Description: "Weekly newsletter recipients",
})
// List with custom fields
list, err := client.Lists.Create(ctx, &mailbreeze.CreateListParams{
Name: "VIP Customers",
Description: "High-value customers",
CustomFields: []mailbreeze.CustomFieldDefinition{
{Key: "company", Label: "Company", Type: "text"},
{Key: "plan", Label: "Plan", Type: "select", Options: []string{"free", "pro", "enterprise"}},
},
})
fmt.Println(list.ID) // "lst_xxx"
$mailbreeze = new MailBreeze('sk_live_xxx');
// Simple list
$list = $mailbreeze->lists->create([
'name' => 'Newsletter Subscribers',
'description' => 'Weekly newsletter recipients',
]);
// List with custom fields
$list = $mailbreeze->lists->create([
'name' => 'VIP Customers',
'description' => 'High-value customers',
'customFields' => [
['key' => 'company', 'label' => 'Company', 'type' => 'text'],
['key' => 'plan', 'label' => 'Plan', 'type' => 'select', 'options' => ['free', 'pro', 'enterprise']],
],
]);
echo $list['id']; // "lst_xxx"
let client = Client::new("sk_live_xxx");
// Simple list
let list = client.lists().create(CreateListParams {
name: "Newsletter Subscribers".to_string(),
description: Some("Weekly newsletter recipients".to_string()),
custom_fields: None,
}).await?;
// List with custom fields
let list = client.lists().create(CreateListParams {
name: "VIP Customers".to_string(),
description: Some("High-value customers".to_string()),
custom_fields: Some(vec![
CustomFieldDefinition {
key: "company".to_string(),
label: "Company".to_string(),
field_type: "text".to_string(),
..Default::default()
},
]),
}).await?;
println!("{}", list.id); // "lst_xxx"
curl -X POST https://api.mailbreeze.com/api/v1/contact-lists \
-H "Authorization: Bearer sk_live_xxx" \
-H "Content-Type: application/json" \
-d '{
"name": "Newsletter Subscribers",
"description": "Weekly newsletter recipients",
"customFields": [
{ "key": "company", "label": "Company", "type": "text" },
{ "key": "plan", "label": "Plan", "type": "select", "options": ["free", "pro", "enterprise"] }
]
}'
Response
Unique list ID.
List name.
List description.
Custom field definitions.
Number of contacts (0 for new lists).
ISO 8601 timestamp when created.
ISO 8601 timestamp when last updated.
Example Response
{
"success": true,
"data": {
"domainId": "6911cf4253eb3ff3b4de6215",
"userId": "68da571fdc22fcf0773dcb33",
"name": "VIP Customers",
"description": "High-value customers",
"totalContacts": 0,
"activeContacts": 0,
"suppressedContacts": 0,
"tags": [],
"createdAt": "2025-12-27T12:46:07.070Z",
"updatedAt": "2025-12-27T12:46:07.070Z",
"id": "694fd50f9e63563857ae96bb"
},
"meta": {
"timestamp": "2025-12-27T12:46:07.123Z",
"requestId": "abc123-def456",
"path": "/api/v1/contact-lists"
}
}
Custom Field Types
| Type | Description | Example Value |
|---|---|---|
text | Free-form text | "Acme Corp" |
number | Numeric value | 99.99 |
date | ISO 8601 date | "2024-01-15" |
boolean | True/false | true |
select | Single choice from options | "pro" |
Custom fields are defined at the list level. All contacts in a list share the same field schema.
⌘I