Skip to main content
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

name
string
required
List name (max 100 characters).
description
string
Optional description (max 500 characters).
customFields
array
Custom field definitions for contacts in this list.

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

id
string
Unique list ID.
name
string
List name.
description
string
List description.
customFields
array
Custom field definitions.
contactCount
integer
Number of contacts (0 for new lists).
createdAt
string
ISO 8601 timestamp when created.
updatedAt
string
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

TypeDescriptionExample Value
textFree-form text"Acme Corp"
numberNumeric value99.99
dateISO 8601 date"2024-01-15"
booleanTrue/falsetrue
selectSingle choice from options"pro"
Custom fields are defined at the list level. All contacts in a list share the same field schema.