# Contacts

> Contacts are the people in your workspace. See how contacts, audiences and subscribers relate, what the Contacts list and profile show, and how opt-outs work.

A contact is one person in your workspace, identified by their email address. Contacts hold the names and custom field values you use to personalize campaigns, and they join audiences, which are the lists campaigns send to. This page explains how the pieces fit together and what you can do with contacts in the dashboard and the API.

## Contacts, audiences and subscribers

Emailit keeps people and lists apart. A person exists once as a contact, and each list they're on is a separate subscriber record with its own opt-in state.

| | Contact | Audience | Subscriber |
| --- | --- | --- | --- |
| **What it is** | One person | A named list you send campaigns to | One contact's membership in one audience |
| **ID prefix** | `con_` | `aud_` | `sub_` |
| **Unique by** | Email address, per workspace | Name, per workspace | One per contact per audience |
| **Holds** | Email, first name, last name, custom fields, marketing status | Name, subscriber count, subscribe URL | A **Subscribed** flag with subscribed and unsubscribed dates |
| **Deleting it** | Also removes the contact from every audience | Removes all its subscribers. The contacts stay. | Removes that membership. The contact stays. |

```text
Workspace
├── Contacts ────────────── one per email address
│   ├── email, first_name, last_name, custom_fields
│   └── marketing status (unsubscribed: true | false)
└── Audiences ───────────── named lists, for example "Newsletter"
    └── Subscribers ─────── one per contact on the list
        └── subscribed: true | false
```

In practice:

- One contact can be a subscriber of many audiences, with a separate **Subscribed** flag in each.
- Adding someone to an audience by email creates the contact first if it doesn't exist yet.
- Names and custom fields live on the contact. Editing them from an audience changes the contact, so the change shows everywhere.

### Who receives a campaign

A campaign goes to every contact that meets all three conditions:

1. The contact is a subscriber of at least one of the campaign's audiences, with **Subscribed** on.
2. The contact's marketing status is **Subscribed**.
3. The address isn't on your [suppression list](/docs/suppressions/).

A contact in several of the selected audiences gets one copy. See [Create a campaign](/docs/campaigns/create/) for the full rules.

## Marketing status

Every contact also has a workspace-wide **Marketing status**: **Subscribed** or **Unsubscribed** (the `unsubscribed` field in the API). It's a global opt-out that sits above the per-audience flag.

| You change | How | Effect on campaigns |
| --- | --- | --- |
| Marketing status | Bulk **Unsubscribe** or **Resubscribe** on the Contacts list, or `unsubscribed` in the API | **Unsubscribed** contacts are skipped in every audience. Their audience memberships don't change. |
| One audience subscription | **Unsubscribe** or **Resubscribe** on the contact page or in the audience, or `subscribed` on the subscriber | The contact is skipped only for campaigns to that audience. |
| The recipient clicks the unsubscribe link | The hosted unsubscribe page | The contact is unsubscribed from every audience it belongs to. |

Marketing status and audience subscriptions control campaigns only. They don't block emails you send with the API or SMTP, or emails sent by automations. To stop all mail to an address, add it to your [suppressions](/docs/suppressions/). [Unsubscribes](/docs/audiences/unsubscribes/) covers every opt-out path.

## The Contacts list

Open **Email Marketing → Contacts** to see every contact in the workspace, newest first.

- **Columns.** **Email** is always shown. Turn **First name**, **Last name**, **Audiences**, **Created** and **Updated** on or off under **Display options > Edit columns**, or select **Show full name** to merge the names into one **Name** column. In the **Audiences** column, each audience badge is green while the contact is subscribed to it and red after they unsubscribe.
- **Search** matches email, first name and last name.
- **Filter** by Email, Name, First name, Last name, Unsubscribed, Created, Updated, Audiences or Audience, and by any [custom field](/docs/contacts/custom-fields/). With two or more filters, choose whether to match all of them or any of them.
- **Sort** by selecting a column header.
- **Import** and **Export** move contacts in and out as files. See [Import and export contacts](/docs/contacts/import-export/).

Select a row to open the contact. The row menu has **Edit** and **Delete**.

### Add a contact

Select **Add contact** and enter the **Email**, and optionally **First name**, **Last name** and **Audiences**. Select **Show custom fields** to fill in custom field values. An email address can only exist once per workspace, so adding an existing address fails.

To change a contact later, select **Edit**. You can change the names and custom fields. The email address can't be changed in the dashboard. Use the `email` field of [Update a contact](/docs/api-reference/contacts/update/) instead.

### Bulk actions

Select contacts with the checkboxes (the header checkbox selects the whole page), then open **Actions**. Each action applies to up to 100 contacts at a time.

| Action | What it does |
| --- | --- |
| **Add to audience** | Adds the contacts to the audience you pick. Existing memberships stay as they are. Contacts whose marketing status is **Unsubscribed** join as unsubscribed subscribers. |
| **Remove from audience** | Deletes their membership in the audience you pick. The contacts stay. |
| **Unsubscribe** | Sets their marketing status to **Unsubscribed**. |
| **Resubscribe** | Sets their marketing status back to **Subscribed**. Audience subscriptions don't change. |
| **Delete** | Deletes the contacts and all their memberships. This can't be undone. |

## The contact page

The contact page shows everything Emailit knows about one person. Use **Edit** and **Delete** at the top.

| Section | What it shows |
| --- | --- |
| **Details** | Email, first name, last name, marketing status, created and updated dates. |
| **Custom fields** | Every custom field defined in the workspace and the contact's value. |
| **Metrics and Insights** | **Emails sent**, **Loads**, **Clicks**, **Last activity**, **Subscribed audiences** (subscribed out of total) and **Marketing status**. The counts include every outgoing email sent to the address, not only campaigns. |
| **Audiences** | Each audience the contact belongs to, with its status and subscribed and unsubscribed dates. The row menu can **Unsubscribe** or **Resubscribe** the contact for that audience, or **Remove from audience**. **Add to audience** adds a new membership. |
| **Sent emails** | Outgoing emails sent to the address, with subject, status, campaign, loads, clicks and send time. |
| **Activity log** | A timeline of events for the contact, such as "Contact created", "Added to Newsletter", "Unsubscribed from Newsletter" and "Email delivered". |

## Use the API

The [Contacts API](/docs/api-reference/contacts/) covers everything the list and profile do, except importing files:

- [Create](/docs/api-reference/contacts/create/), [retrieve](/docs/api-reference/contacts/get/), [update](/docs/api-reference/contacts/update/), [list](/docs/api-reference/contacts/list/) and [delete](/docs/api-reference/contacts/delete/) contacts. Wherever an ID is expected, you can pass the contact's email address instead of its `con_` ID.
- Pass `audiences` (an array of `aud_` IDs) when you create a contact to subscribe it right away. On update, `audiences` replaces the contact's memberships.
- [Run a bulk action](/docs/api-reference/contacts/bulk/) on up to 100 contacts, and [export](/docs/api-reference/contacts/export/) up to 10,000 as CSV or XLSX.

```bash
curl https://api.emailit.com/v2/contacts \
  -X POST \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "ada@example.com",
    "first_name": "Ada",
    "last_name": "Lovelace",
    "custom_fields": { "company": "Acme", "plan": "pro" },
    "audiences": ["aud_2kq8Vt4xLm7Rz"]
  }'
```

Creating a contact with an email that already exists returns `409` with the existing contact in `existing`. The Contacts API needs an API key with **Full Access**.

Contact changes produce [`contact.created`, `contact.updated` and `contact.deleted`](/docs/webhooks/events/contact/) events, and membership changes produce [`subscriber.*`](/docs/webhooks/events/subscriber/) events, which you can receive with [webhooks](/docs/webhooks/).

## Next steps

  - [Custom fields](/docs/contacts/custom-fields/): Store extra data on contacts and use it in filters and emails.
  - [Import and export](/docs/contacts/import-export/): Bring contacts in from a CSV or Excel file, and download them.
  - [Audiences](/docs/audiences/): Group contacts into lists you can send campaigns to.
  - [Unsubscribes](/docs/audiences/unsubscribes/): How opt-outs work and how to respect them.

---
Source: https://emailit.com/docs/contacts/