> ## 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.

# Create Contact

> Create a new contact in a list

Add a new contact to a contact list. The contact's email must be unique within the list.

## Path Parameters

<ParamField path="listId" type="string" required>
  The unique list ID (e.g., `lst_abc123`).
</ParamField>

## Request Body

<ParamField body="email" type="string" required>
  Contact's email address. Must be unique within the list.
</ParamField>

<ParamField body="firstName" type="string">
  Contact's first name.
</ParamField>

<ParamField body="lastName" type="string">
  Contact's last name.
</ParamField>

<ParamField body="phoneNumber" type="string">
  Contact's phone number.
</ParamField>

<ParamField body="customFields" type="object">
  Key-value pairs matching the list's custom field definitions.
</ParamField>

<ParamField body="source" type="string">
  How the contact was acquired (e.g., `api`, `import`, `form`, `manual`).
</ParamField>

<ParamField body="consentType" type="string">
  Type of consent obtained (NDPR compliance): `explicit`, `implicit`, or `legitimate_interest`.
</ParamField>

<ParamField body="consentSource" type="string">
  Where consent was collected (e.g., `signup_form`, `import`, `api`).
</ParamField>

<ParamField body="consentTimestamp" type="string">
  ISO 8601 timestamp when consent was given.
</ParamField>

<ParamField body="consentIpAddress" type="string">
  IP address from which consent was given.
</ParamField>

## Examples

<CodeGroup>
  ```typescript JavaScript theme={null}
  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",
    },
  });
  ```

  ```python Python theme={null}
  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",
      },
  )
  ```

  ```go Go theme={null}
  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",
      },
  })
  ```

  ```php PHP theme={null}
  $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'];
  ```

  ```rust Rust theme={null}
  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?;
  ```

  ```bash cURL theme={null}
  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"
      }
    }'
  ```
</CodeGroup>

## Response

<ResponseField name="id" type="string">
  Unique contact ID.
</ResponseField>

<ResponseField name="email" type="string">
  Contact's email address.
</ResponseField>

<ResponseField name="firstName" type="string">
  Contact's first name.
</ResponseField>

<ResponseField name="lastName" type="string">
  Contact's last name.
</ResponseField>

<ResponseField name="phoneNumber" type="string">
  Contact's phone number.
</ResponseField>

<ResponseField name="customFields" type="object">
  Custom field values.
</ResponseField>

<ResponseField name="status" type="string">
  Contact status: `active`, `unsubscribed`, `bounced`, `complained`, or `suppressed`.
</ResponseField>

<ResponseField name="source" type="string">
  Acquisition source.
</ResponseField>

<ResponseField name="createdAt" type="string">
  ISO 8601 timestamp when created.
</ResponseField>

<ResponseField name="updatedAt" type="string">
  ISO 8601 timestamp when last updated.
</ResponseField>

<ResponseField name="subscribedAt" type="string">
  ISO 8601 timestamp when subscribed.
</ResponseField>

<ResponseField name="consentType" type="string">
  Type of consent: `explicit`, `implicit`, or `legitimate_interest`.
</ResponseField>

<ResponseField name="consentSource" type="string">
  Where consent was collected.
</ResponseField>

<ResponseField name="consentTimestamp" type="string">
  ISO 8601 timestamp when consent was given.
</ResponseField>

<ResponseField name="consentIpAddress" type="string">
  IP address from which consent was given.
</ResponseField>

```json Example Response theme={null}
{
  "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

| Code                     | HTTP Status | Description                                    |
| ------------------------ | ----------- | ---------------------------------------------- |
| `CONTACT_ALREADY_EXISTS` | 409         | Email already exists in this list              |
| `LIST_NOT_FOUND`         | 404         | List with this ID doesn't exist                |
| `INVALID_CUSTOM_FIELD`   | 400         | Custom field key or value is invalid           |
| `VALIDATION_ERROR`       | 400         | Invalid email format or required field missing |