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>"
}
'
{
  "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>"
}

Documentation Index

Fetch the complete documentation index at: https://docs.mailbreeze.com/llms.txt

Use this file to discover all available pages before exploring further.

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",
  },
});

​
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