> ## Documentation Index
> Fetch the complete documentation index at: https://docs.emailr.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Managing Contacts

> Learn how to work with Contacts with Emailr.

Contacts in Emailr are global entities linked to a specific email address. After adding Contacts, send [Broadcasts](/docs/guides/dashboard/broadcasts/introduction) to groups of Contacts.

<Tip>
  If you previously used our Audience model, learn how to [migrate to the new
  Contacts model](/docs/guides/dashboard/segments/migrating-from-audiences-to-segments).
</Tip>

## Add Contacts

You can add a Contact in three different ways: via API, CSV upload, or manually.

### 1. Add Contacts programmatically via API

You can add contacts programmatically using the [contacts](/docs/api/contacts/create-contact) endpoint.

<CodeGroup>
  ```ts Node.js theme={null} theme={null}
  import { Emailr } from 'emailr';

  const emailr = new Emailr('em_xxxxxxxxx');

  emailr.contacts.create({
    email: 'steve.wozniak@gmail.com',
    firstName: 'Steve',
    lastName: 'Wozniak',
  });
  ```

  ```php PHP theme={null} theme={null}
  $emailr = Emailr::client('em_xxxxxxxxx');

  $emailr->contacts->create(
    parameters: [
      'email' => 'steve.wozniak@gmail.com',
      'first_name' => 'Steve',
      'last_name' => 'Wozniak',
    ]
  );
  ```

  ```python Python theme={null} theme={null}
  import emailr

  emailr.api_key = "em_xxxxxxxxx"

  params: emailr.Contacts.CreateParams = {
    "email": "steve.wozniak@gmail.com",
    "first_name": "Steve",
    "last_name": "Wozniak",
  }

  emailr.Contacts.create(params)
  ```

  ```ruby Ruby theme={null} theme={null}
  require "emailr"

  Emailr.api_key = "em_xxxxxxxxx"

  params = {
    "email": "steve.wozniak@gmail.com",
    "first_name": "Steve",
    "last_name": "Wozniak",
  }

  Emailr::Contacts.create(params)
  ```

  ```go Go theme={null} theme={null}
  import 	"github.com/emailr/emailr-go/v2"

  client := emailr.NewClient("em_xxxxxxxxx")

  params := &emailr.CreateContactRequest{
    Email:        "steve.wozniak@gmail.com",
    FirstName:    "Steve",
    LastName:     "Wozniak",
  }

  contact, err := client.Contacts.Create(params)
  ```

  ```rust Rust theme={null} theme={null}
  use emailr_rs::{types::ContactData, Emailr, Result};

  #[tokio::main]
  async fn main() -> Result<()> {
    let emailr = Emailr::new("em_xxxxxxxxx");

    let contact = ContactData::new("steve.wozniak@gmail.com")
      .with_first_name("Steve")
      .with_last_name("Wozniak");

    let _contact = emailr
      .contacts
      .create(contact)
      .await?;

    Ok(())
  }
  ```

  ```java Java theme={null} theme={null}
  import com.emailr.*;

  public class Main {
      public static void main(String[] args) {
          Emailr emailr = new Emailr("em_xxxxxxxxx");

          CreateContactOptions params = CreateContactOptions.builder()
                  .email("steve.wozniak@gmail.com")
                  .firstName("Steve")
                  .lastName("Wozniak")
                  .build();

          CreateContactResponseSuccess data = emailr.contacts().create(params);
      }
  }
  ```

  ```bash cURL theme={null} theme={null}
  curl -X POST 'https://api.emailr.dev/contacts' \
       -H 'Authorization: Bearer em_xxxxxxxxx' \
       -H 'Content-Type: application/json' \
       -d $'{
    "email": "steve.wozniak@gmail.com",
    "first_name": "Steve",
    "last_name": "Wozniak"
  }'
  ```
</CodeGroup>

When creating a Contact, you can optionally set the following properties:

* `first_name`: The first name of the contact.
* `last_name`: The last name of the contact.
* `unsubscribed`: Whether the contact is unsubscribed from all Broadcasts.
* `properties`: A map of custom property keys and values to create (learn more about [custom properties](/docs/guides/dashboard/audiences/properties)).

Once a Contact is created, you can update it using the [update contact](/docs/api/contacts/update-contact) endpoint or [add the contact to a Segment](/docs/api/segments/add-contact-to-segment).

### 2. Add Contacts by uploading a .csv

You can also add Contacts by uploading a .csv file. This is a convenient way to add multiple Contacts at once.

1. Go to the [Contacts](https://app.emailr.dev/dashboard/contacts) page, and select **Add Contacts**.
2. Select **Import CSV**.
3. Upload your CSV file from your computer.
4. Map the fields you want to use. You can map the fields to: `email`, `first_name`, `last_name`, and `unsubscribed`, or any Contact properties you've already created.
5. Optionally add the contacts to an existing Segment.
6. Select **Continue**, review the contacts, and finish the upload.

### 3. Add Contacts manually

1. Go to the [Contacts](https://app.emailr.dev/dashboard/contacts) page, and select **Add Contacts**.
2. Select **Add Manually**.
3. Add the email address of the contact in the text field (separated by commas or new lines for multiple contacts).
4. Optionally add the contact to an existing Segment.
5. Confirm and click **Add**.

## Contact Properties

Contact Properties can be used to store additional information about your Contacts and then personalize your Broadcasts.

<img alt="Screenshot placeholder" src="https://mintcdn.com/emailrdev/tSm2WeCvU8-lHmTx/images/placeholder.svg?fit=max&auto=format&n=tSm2WeCvU8-lHmTx&q=85&s=93891ced94bad8f8c38f90b5be99f73c" width="800" height="450" data-path="images/placeholder.svg" />

Emailr includes a few default properties:

* `first_name`: The first name of the contact.
* `last_name`: The last name of the contact.
* `unsubscribed`: Whether the contact is unsubscribed from all Broadcasts.
* `email`: The email address of the contact.

You can create additional custom Contact Properties for your Contacts to store additional information. These properties can be used to personalize your Broadcasts across all Segments.

Learn more about [Contact Properties](/docs/guides/dashboard/audiences/properties).

## View Contacts

You can view your Contacts in the [Contacts](https://app.emailr.dev/dashboard/contacts) page.

1. Go to the [Contacts](https://app.emailr.dev/dashboard/contacts) page.
2. Click on the Contact you want to view.
3. View the Contact details.

Each Contact includes the metadata associated with the contact, as well as a full history of all marketing interactions with the Contact.

<img alt="Screenshot placeholder" src="https://mintcdn.com/emailrdev/tSm2WeCvU8-lHmTx/images/placeholder.svg?fit=max&auto=format&n=tSm2WeCvU8-lHmTx&q=85&s=93891ced94bad8f8c38f90b5be99f73c" width="800" height="450" data-path="images/placeholder.svg" />

You can also retrieve a [single Contact](/docs/api/contacts/get-contact) or [list all Contacts](/docs/api/contacts/list-contacts) via the API or SDKs.

## Edit Contacts

1. Go to the [Contacts](https://app.emailr.dev/dashboard/contacts) page.
2. Click on the **More options** <Icon icon="ellipsis" iconType="solid" /> button and then **Edit Contact**.
3. Edit the Contact details and choose **Save**.

You can edit any Contact property (excluding the email address), assign
the Contact to a [Segment](/docs/guides/dashboard/segments/introduction) or [Topic](/docs/guides/dashboard/topics/introduction), or unsubscribe the Contact from all Broadcasts.

You can also [update a Contact](/docs/api/contacts/update-contact) via the API or SDKs using the `id` or `email` of the Contact.

<CodeGroup>
  ```ts Node.js theme={null} theme={null}
  import { Emailr } from 'emailr';

  const emailr = new Emailr('em_xxxxxxxxx');

  // Update by contact id
  const { data, error } = await emailr.contacts.update({
    id: 'e169aa45-1ecf-4183-9955-b1499d5701d3',
    unsubscribed: true,
  });

  // Update by contact email
  const { data, error } = await emailr.contacts.update({
    email: 'acme@example.com',
    unsubscribed: true,
  });
  ```

  ```php PHP theme={null} theme={null}
  $emailr = Emailr::client('em_xxxxxxxxx');

  // Update by contact id
  $emailr->contacts->update(
    id: 'e169aa45-1ecf-4183-9955-b1499d5701d3',
    parameters: [
      'unsubscribed' => true
    ]
  );

  // Update by contact email
  $emailr->contacts->update(
    email: 'acme@example.com',
    parameters: [
      'unsubscribed' => true
    ]
  );
  ```

  ```python Python theme={null} theme={null}
  import emailr

  emailr.api_key = "em_xxxxxxxxx"

  # Update by contact id
  params: emailr.Contacts.UpdateParams = {
    "id": "e169aa45-1ecf-4183-9955-b1499d5701d3",
    "unsubscribed": True,
  }

  emailr.Contacts.update(params)

  # Update by contact email
  params: emailr.Contacts.UpdateParams = {
    "email": "acme@example.com",
    "unsubscribed": True,
  }

  emailr.Contacts.update(params)
  ```

  ```ruby Ruby theme={null} theme={null}
  require "emailr"

  Emailr.api_key = "em_xxxxxxxxx"

  # Update by contact id
  params = {
    "id": "e169aa45-1ecf-4183-9955-b1499d5701d3",
    "unsubscribed": true,
  }

  Emailr::Contacts.update(params)

  # Update by contact email
  params = {
    "email": "acme@example.com",
    "unsubscribed": true,
  }

  Emailr::Contacts.update(params)
  ```

  ```go Go theme={null} theme={null}
  import "github.com/emailr/emailr-go/v3"

  client := emailr.NewClient("em_xxxxxxxxx")

  // Update by contact id
  params := &emailr.UpdateContactRequest{
    Id:           "e169aa45-1ecf-4183-9955-b1499d5701d3",
    Unsubscribed: true,
  }
  params.SetUnsubscribed(true)

  contact, err := client.Contacts.Update(params)

  // Update by contact email
  params = &emailr.UpdateContactRequest{
    Email:        "acme@example.com",
    Unsubscribed: true,
  }
  params.SetUnsubscribed(true)

  contact, err := client.Contacts.Update(params)
  ```

  ```rust Rust theme={null} theme={null}
  use emailr_rs::{types::ContactChanges, Emailr, Result};

  #[tokio::main]
  async fn main() -> Result<()> {
    let emailr = Emailr::new("em_xxxxxxxxx");

    let changes = ContactChanges::new().with_unsubscribed(true);

    // Update by contact id
    let _contact = emailr
      .contacts
      .update("e169aa45-1ecf-4183-9955-b1499d5701d3", changes.clone())
      .await?;

    // Update by contact email
    let _contact = emailr
      .contacts
      .update("acme@example.com", changes)
      .await?;

    Ok(())
  }
  ```

  ```java Java theme={null} theme={null}
  import com.emailr.*;

  public class Main {
      public static void main(String[] args) {
          Emailr emailr = new Emailr("em_xxxxxxxxx");

          // Update by contact id
          UpdateContactOptions params = UpdateContactOptions.builder()
                  .id("e169aa45-1ecf-4183-9955-b1499d5701d3")
                  .unsubscribed(true)
                  .build();

          // Update by contact email
          UpdateContactOptions params = UpdateContactOptions.builder()
                  .email("acme@example.com")
                  .unsubscribed(true)
                  .build();

          UpdateContactResponseSuccess data = emailr.contacts().update(params);
      }
  }
  ```

  ```csharp .NET theme={null} theme={null}
  using Emailr;

  IEmailr emailr = EmailrClient.Create( "em_xxxxxxxxx" ); // Or from DI

  // By Id
  await emailr.ContactUpdateAsync(
      contactId: new Guid( "e169aa45-1ecf-4183-9955-b1499d5701d3" ),
      new ContactData()
      {
          FirstName = "Stevie",
          LastName = "Wozniaks",
          IsUnsubscribed = true,
      }
  );

  // By Email
  await emailr.ContactUpdateByEmailAsync(
      "acme@example.com",
      new ContactData()
      {
          FirstName = "Stevie",
          LastName = "Wozniaks",
          IsUnsubscribed = true,
      }
  );
  ```

  ```bash cURL theme={null} theme={null}
  # Update by contact id
  curl -X PATCH 'https://api.emailr.dev/contacts/520784e2-887d-4c25-b53c-4ad46ad38100' \
       -H 'Authorization: Bearer em_xxxxxxxxx' \
       -H 'Content-Type: application/json' \
       -d $'{
    "unsubscribed": true
  }'

  # Update by contact email
  curl -X PATCH 'https://api.emailr.dev/contacts/acme@example.com' \
       -H 'Authorization: Bearer em_xxxxxxxxx' \
       -H 'Content-Type: application/json' \
       -d $'{
    "unsubscribed": true
  }'
  ```
</CodeGroup>

## Delete Contacts

1. Go to the [Contacts](https://app.emailr.dev/dashboard/contacts) page.
2. Click on the **More options** <Icon icon="ellipsis" iconType="solid" /> button and then **Delete Contact**.
3. Confirm the deletion.

You can also [delete a Contact](/docs/api/contacts/delete-contact) via the API or SDKs.

<CodeGroup>
  ```ts Node.js theme={null} theme={null}
  import { Emailr } from 'emailr';

  const emailr = new Emailr('em_xxxxxxxxx');

  // Delete by contact id
  const { data, error } = await emailr.contacts.remove({
    id: '520784e2-887d-4c25-b53c-4ad46ad38100',
  });

  // Delete by contact email
  const { data, error } = await emailr.contacts.remove({
    email: 'acme@example.com',
  });
  ```

  ```php PHP theme={null} theme={null}
  $emailr = Emailr::client('em_xxxxxxxxx');

  // Delete by contact id
  $emailr->contacts->remove(
    id: '520784e2-887d-4c25-b53c-4ad46ad38100'
  );

  // Delete by contact email
  $emailr->contacts->remove(
    email: 'acme@example.com'
  );
  ```

  ```python Python theme={null} theme={null}
  import emailr

  emailr.api_key = "em_xxxxxxxxx"

  # Delete by contact id
  emailr.Contacts.remove(
    id="520784e2-887d-4c25-b53c-4ad46ad38100"
  )

  # Delete by contact email
  emailr.Contacts.remove(
    email="acme@example.com"
  )
  ```

  ```ruby Ruby theme={null} theme={null}
  require "emailr"

  Emailr.api_key = "em_xxxxxxxxx"

  # Delete by contact id
  Emailr::Contacts.remove(
    "520784e2-887d-4c25-b53c-4ad46ad38100"
  )

  # Delete by contact email
  Emailr::Contacts.remove(
    email: "acme@example.com",
  )
  ```

  ```go Go theme={null} theme={null}
  import "github.com/emailr/emailr-go/v3"

  client := emailr.NewClient("em_xxxxxxxxx")

  // Delete by contact id
  removed, err := client.Contacts.Remove(
    "520784e2-887d-4c25-b53c-4ad46ad38100"
  )

  // Delete by contact email
  removed, err := client.Contacts.Remove(
    "acme@example.com"
  )
  ```

  ```rust Rust theme={null} theme={null}
  use emailr_rs::{Emailr, Result};

  #[tokio::main]
  async fn main() -> Result<()> {
    let emailr = Emailr::new("em_xxxxxxxxx");

    // Delete by contact id
    let _deleted = emailr
      .contacts
      .delete("520784e2-887d-4c25-b53c-4ad46ad38100")
      .await?;

    // Delete by contact email
    let _deleted = emailr
      .contacts
      .delete("acme@example.com")
      .await?;

    Ok(())
  }
  ```

  ```java Java theme={null} theme={null}
  import com.emailr.*;

  public class Main {
      public static void main(String[] args) {
          Emailr emailr = new Emailr("em_xxxxxxxxx");

          // Delete by contact id
          emailr.contacts().remove(ContactRequestOptions.builder()
                          .id("520784e2-887d-4c25-b53c-4ad46ad38100")
                          .build());

          // Delete by contact email
          emailr.contacts().remove(ContactRequestOptions.builder()
                          .email("acme@example.com")
                          .build());
      }
  }
  ```

  ```csharp .NET theme={null} theme={null}
  using Emailr;

  IEmailr emailr = EmailrClient.Create( "em_xxxxxxxxx" ); // Or from DI

  // By Id
  await emailr.ContactDeleteAsync(
      contactId: new Guid( "520784e2-887d-4c25-b53c-4ad46ad38100" )
  );

  // By Email
  await emailr.ContactDeleteByEmailAsync(
      "acme@example.com"
  );
  ```

  ```bash cURL theme={null} theme={null}
  # Delete by contact id
  curl -X DELETE 'https://api.emailr.dev/contacts/520784e2-887d-4c25-b53c-4ad46ad38100' \
       -H 'Authorization: Bearer em_xxxxxxxxx'

  # Deleted by contact email
  curl -X DELETE 'https://api.emailr.dev/contacts/acme@example.com' \
       -H 'Authorization: Bearer em_xxxxxxxxx'
  ```
</CodeGroup>