Skip to main content
POST
/
api
/
v1
/
contact-lists
/
{listId}
/
contacts
Create Contact
curl --request POST \
  --url https://api.example.com/api/v1/contact-lists/{listId}/contacts \
  --header 'Content-Type: application/json' \
  --data '
{
  "email": "<string>",
  "firstName": "<string>",
  "lastName": "<string>",
  "phoneNumber": "<string>",
  "customFields": {},
  "source": "<string>",
  "consentType": "<string>",
  "consentSource": "<string>",
  "consentTimestamp": "<string>",
  "consentIpAddress": "<string>"
}
'
import requests

url = "https://api.example.com/api/v1/contact-lists/{listId}/contacts"

payload = {
    "email": "<string>",
    "firstName": "<string>",
    "lastName": "<string>",
    "phoneNumber": "<string>",
    "customFields": {},
    "source": "<string>",
    "consentType": "<string>",
    "consentSource": "<string>",
    "consentTimestamp": "<string>",
    "consentIpAddress": "<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({
    email: '<string>',
    firstName: '<string>',
    lastName: '<string>',
    phoneNumber: '<string>',
    customFields: {},
    source: '<string>',
    consentType: '<string>',
    consentSource: '<string>',
    consentTimestamp: '<string>',
    consentIpAddress: '<string>'
  })
};

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 => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'email' => '<string>',
    'firstName' => '<string>',
    'lastName' => '<string>',
    'phoneNumber' => '<string>',
    'customFields' => [
        
    ],
    'source' => '<string>',
    'consentType' => '<string>',
    'consentSource' => '<string>',
    'consentTimestamp' => '<string>',
    'consentIpAddress' => '<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/{listId}/contacts"

	payload := strings.NewReader("{\n  \"email\": \"<string>\",\n  \"firstName\": \"<string>\",\n  \"lastName\": \"<string>\",\n  \"phoneNumber\": \"<string>\",\n  \"customFields\": {},\n  \"source\": \"<string>\",\n  \"consentType\": \"<string>\",\n  \"consentSource\": \"<string>\",\n  \"consentTimestamp\": \"<string>\",\n  \"consentIpAddress\": \"<string>\"\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/{listId}/contacts")
  .header("Content-Type", "application/json")
  .body("{\n  \"email\": \"<string>\",\n  \"firstName\": \"<string>\",\n  \"lastName\": \"<string>\",\n  \"phoneNumber\": \"<string>\",\n  \"customFields\": {},\n  \"source\": \"<string>\",\n  \"consentType\": \"<string>\",\n  \"consentSource\": \"<string>\",\n  \"consentTimestamp\": \"<string>\",\n  \"consentIpAddress\": \"<string>\"\n}")
  .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::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"email\": \"<string>\",\n  \"firstName\": \"<string>\",\n  \"lastName\": \"<string>\",\n  \"phoneNumber\": \"<string>\",\n  \"customFields\": {},\n  \"source\": \"<string>\",\n  \"consentType\": \"<string>\",\n  \"consentSource\": \"<string>\",\n  \"consentTimestamp\": \"<string>\",\n  \"consentIpAddress\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body
{
  "id": "<string>",
  "email": "<string>",
  "firstName": "<string>",
  "lastName": "<string>",
  "phoneNumber": "<string>",
  "customFields": {},
  "status": "<string>",
  "source": "<string>",
  "createdAt": "<string>",
  "updatedAt": "<string>",
  "subscribedAt": "<string>",
  "consentType": "<string>",
  "consentSource": "<string>",
  "consentTimestamp": "<string>",
  "consentIpAddress": "<string>"
}
Add a new contact to a contact list. The contact’s email must be unique within the list.

​
Path Parameters

​
listId
string
required
The unique list ID (e.g., lst_abc123).

​
Request Body

​
email
string
required
Contact’s email address. Must be unique within the list.
​
firstName
string
Contact’s first name.
​
lastName
string
Contact’s last name.
​
phoneNumber
string
Contact’s phone number.
​
customFields
object
Key-value pairs matching the list’s custom field definitions.
​
source
string
How the contact was acquired (e.g., api, import, form, manual).
​
consentType
string
Type of consent obtained (NDPR compliance): explicit, implicit, or legitimate_interest.
​
consentSource
string
Where consent was collected (e.g., signup_form, import, api).
​
consentTimestamp
string
ISO 8601 timestamp when consent was given.
​
consentIpAddress
string
IP address from which consent was given.

​
Examples

import { MailBreeze } from "mailbreeze";

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

// Get contacts for a specific list
const contacts = mailbreeze.contacts("lst_abc123");

// Create a simple contact
const contact = await contacts.create({
  email: "user@example.com",
  firstName: "John",
  lastName: "Doe",
});

console.log(contact.id); // "cnt_xxx"

// Create with custom fields
const contact = await contacts.create({
  email: "jane@example.com",
  firstName: "Jane",
  lastName: "Smith",
  phoneNumber: "+1-555-0123",
  source: "api",
  customFields: {
    company: "Acme Inc",
    plan: "enterprise",
    signupDate: "2024-01-15",
  },
});

from mailbreeze import MailBreeze

client = MailBreeze(api_key="sk_live_xxx")

# Get contacts for a specific list
contacts = client.contacts("lst_abc123")

# Create a simple contact
contact = await contacts.create(
    email="user@example.com",
    first_name="John",
    last_name="Doe",
)

print(contact.id)  # "cnt_xxx"

# Create with custom fields
contact = await contacts.create(
    email="jane@example.com",
    first_name="Jane",
    last_name="Smith",
    phone_number="+1-555-0123",
    source="api",
    custom_fields={
        "company": "Acme Inc",
        "plan": "enterprise",
    },
)

client := mailbreeze.NewClient("sk_live_xxx")

// Get contacts for a specific list
contacts := client.Contacts("lst_abc123")

// Create a simple contact
contact, err := contacts.Create(ctx, &mailbreeze.CreateContactParams{
    Email:     "user@example.com",
    FirstName: "John",
    LastName:  "Doe",
})
if err != nil {
    log.Fatal(err)
}

fmt.Println(contact.ID) // "cnt_xxx"

// Create with custom fields
contact, err := contacts.Create(ctx, &mailbreeze.CreateContactParams{
    Email:     "jane@example.com",
    FirstName: "Jane",
    LastName:  "Smith",
    Source:    "api",
    CustomFields: map[string]any{
        "company": "Acme Inc",
        "plan":    "enterprise",
    },
})

$mailbreeze = new MailBreeze('sk_live_xxx');

// Create a simple contact
$response = $mailbreeze->contacts->create('lst_abc123', [
    'email' => 'user@example.com',
    'firstName' => 'John',
    'lastName' => 'Doe',
]);
$contact = $response['data'];

echo $contact['id']; // "5e858115-df93-40cb-b855-bf5f6cacabe5"

// Create with custom fields
$response = $mailbreeze->contacts->create('lst_abc123', [
    'email' => 'jane@example.com',
    'firstName' => 'Jane',
    'lastName' => 'Smith',
    'source' => 'api',
    'customFields' => [
        'company' => 'Acme Inc',
        'plan' => 'enterprise',
    ],
]);
$contact = $response['data'];

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

// Get contacts for a specific list
let contacts = client.contacts("lst_abc123");

// Create a simple contact
let contact = contacts.create(CreateContactParams {
    email: "user@example.com".to_string(),
    first_name: Some("John".to_string()),
    last_name: Some("Doe".to_string()),
    ..Default::default()
}).await?;

println!("{}", contact.id); // "cnt_xxx"

// Create with custom fields
let contact = contacts.create(CreateContactParams {
    email: "jane@example.com".to_string(),
    first_name: Some("Jane".to_string()),
    last_name: Some("Smith".to_string()),
    source: Some("api".to_string()),
    custom_fields: Some(json!({"company": "Acme Inc", "plan": "enterprise"})),
    ..Default::default()
}).await?;

curl -X POST "https://api.mailbreeze.com/api/v1/contact-lists/694fc1669e63563857ae8d72/contacts" \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "firstName": "John",
    "lastName": "Doe",
    "customFields": {
      "company": "Acme Inc",
      "plan": "enterprise"
    }
  }'

​
Response

​
id
string
Unique contact ID.
​
email
string
Contact’s email address.
​
firstName
string
Contact’s first name.
​
lastName
string
Contact’s last name.
​
phoneNumber
string
Contact’s phone number.
​
customFields
object
Custom field values.
​
status
string
Contact status: active, unsubscribed, bounced, complained, or suppressed.
​
source
string
Acquisition source.
​
createdAt
string
ISO 8601 timestamp when created.
​
updatedAt
string
ISO 8601 timestamp when last updated.
​
subscribedAt
string
ISO 8601 timestamp when subscribed.
​
consentType
string
Type of consent: explicit, implicit, or legitimate_interest.
​
consentSource
string
Where consent was collected.
​
consentTimestamp
string
ISO 8601 timestamp when consent was given.
​
consentIpAddress
string
IP address from which consent was given.
Example Response
{
  "success": true,
  "data": {
    "id": "5e858115-df93-40cb-b855-bf5f6cacabe5",
    "domainId": "6911cf4253eb3ff3b4de6215",
    "contactListId": "694fc1669e63563857ae8d72",
    "email": "newcontact@example.com",
    "status": "active",
    "source": "console",
    "subscriptionToken": "24f646ee92c611afd657685af130f74202fe509ed95f5e5bdc8cbc8030563b3b",
    "createdAt": "2025-12-27T13:40:37.796Z",
    "updatedAt": "2025-12-27T13:40:37.796Z"
  },
  "meta": {
    "timestamp": "2025-12-27T13:40:38.082Z",
    "requestId": "cae3038b-77e2-4a2d-9a39-6f87c0e2917d",
    "path": "/api/v1/contact-lists/694fc1669e63563857ae8d72/contacts"
  }
}

​
Errors

CodeHTTP StatusDescription
CONTACT_ALREADY_EXISTS409Email already exists in this list
LIST_NOT_FOUND404List with this ID doesn’t exist
INVALID_CUSTOM_FIELD400Custom field key or value is invalid
VALIDATION_ERROR400Invalid email format or required field missing