Update List

curl --request PUT \
  --url https://api.example.com/api/v1/contact-lists/{id} \
  --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/{id}"

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.put(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PUT',
  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/{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/api/v1/contact-lists/{id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PUT",
  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/{id}"

	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("PUT", 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.put("https://api.example.com/api/v1/contact-lists/{id}")
  .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/{id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Put.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

PUT

api

contact-lists

{id}

Update List

curl --request PUT \
  --url https://api.example.com/api/v1/contact-lists/{id} \
  --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/{id}"

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.put(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PUT',
  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/{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/api/v1/contact-lists/{id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PUT",
  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/{id}"

	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("PUT", 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.put("https://api.example.com/api/v1/contact-lists/{id}")
  .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/{id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Put.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

Update properties of an existing contact list including name, description, and custom fields.

Path Parameters

string

required

The unique list ID (e.g., lst_abc123).

Request Body

string

New list name (max 100 characters).

string

New description (max 500 characters).

array

Updated custom field definitions. Replaces existing fields.

Show Custom field object

string

required

Field key used in API.

string

required

Display label.

string

required

Field type: text, number, date, boolean, or select.

boolean

Whether field is required.

any

Default value.

string[]

Required for select type.

Examples

import { MailBreeze } from "mailbreeze";

const mailbreeze = new MailBreeze({ apiKey: "sk_live_xxx" });

// Update name and description
const list = await mailbreeze.lists.update("lst_abc123", {
  name: "Premium Newsletter",
  description: "Updated description",
});

// Add new custom field
const list = await mailbreeze.lists.update("lst_abc123", {
  customFields: [
    { key: "company", label: "Company", type: "text" },
    { key: "industry", label: "Industry", type: "select", options: ["tech", "finance", "healthcare"] },
  ],
});

console.log(list.updatedAt); // "2024-01-20T14:15:00Z"

from mailbreeze import MailBreeze

client = MailBreeze(api_key="sk_live_xxx")

# Update name and description
list = await client.lists.update("lst_abc123",
    name="Premium Newsletter",
    description="Updated description",
)

# Add new custom field
list = await client.lists.update("lst_abc123",
    custom_fields=[
        {"key": "company", "label": "Company", "type": "text"},
        {"key": "industry", "label": "Industry", "type": "select", "options": ["tech", "finance"]},
    ],
)

print(list.updated_at)  # "2024-01-20T14:15:00Z"

client := mailbreeze.NewClient("sk_live_xxx")

// Update name and description
list, err := client.Lists.Update(ctx, "lst_abc123", &mailbreeze.UpdateListParams{
    Name:        "Premium Newsletter",
    Description: "Updated description",
})

fmt.Println(list.UpdatedAt) // "2024-01-20T14:15:00Z"

$mailbreeze = new MailBreeze('sk_live_xxx');

// Update name and description
$list = $mailbreeze->lists->update('lst_abc123', [
    'name' => 'Premium Newsletter',
    'description' => 'Updated description',
]);

echo $list['updatedAt']; // "2024-01-20T14:15:00Z"

let client = Client::new("sk_live_xxx");

// Update name and description
let list = client.lists().update("lst_abc123", UpdateListParams {
    name: Some("Premium Newsletter".to_string()),
    description: Some("Updated description".to_string()),
    custom_fields: None,
}).await?;

println!("{}", list.updated_at); // "2024-01-20T14:15:00Z"

curl -X PUT "https://api.mailbreeze.com/api/v1/contact-lists/lst_abc123" \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Premium Newsletter",
    "description": "Updated description"
  }'

Response

Returns the updated contact list object.

Example Response

{
  "success": true,
  "data": {
    "domainId": "6911cf4253eb3ff3b4de6215",
    "userId": "68da571fdc22fcf0773dcb33",
    "name": "Premium Newsletter",
    "description": "Updated description",
    "totalContacts": 1523,
    "activeContacts": 1520,
    "suppressedContacts": 3,
    "tags": [],
    "createdAt": "2025-12-27T11:22:14.221Z",
    "updatedAt": "2025-12-27T14:15:00.000Z",
    "id": "694fc1669e63563857ae8d72"
  },
  "meta": {
    "timestamp": "2025-12-27T14:15:00.123Z",
    "requestId": "abc123-def456",
    "path": "/api/v1/contact-lists/694fc1669e63563857ae8d72"
  }
}

Errors

Code	HTTP Status	Description
`NOT_FOUND`	404	List with this ID doesn’t exist
`VALIDATION_ERROR`	400	Invalid field values or format

Updating customFields replaces the entire array. Include all fields you want to keep.

Overview

Emails

Attachments

Lists

Contacts

Verification

Update List

Path Parameters

Request Body

Examples

Response

Errors

​Path Parameters

​Request Body

​Examples

​Response

​Errors

Path Parameters

Request Body

Examples

Response

Errors