# Tags and lead score

> Label contacts with tags and score their engagement, from the dashboard, the API, the MCP server and automation steps, and use both in filters, triggers and conditions.

Tags are short labels on a contact, such as `customer`, `vip` or `webinar-2026`. The lead score is a whole number on each contact that you raise or lower as they engage, for example `+10` for a click. Both are meant for flows: they start automations, end them, and route contacts down branches, and your app or CRM can set them with the API.

| | Tags | Lead score |
| --- | --- | --- |
| Stores | Any number of labels | One whole number, starting at 0 |
| Set from | Contact page, create dialog, API, MCP, **Add tags** and **Remove tags** steps | Contact page, API, MCP, **Update score** steps |
| Filter contacts | **All tags** filter on the contacts list | **Score** column (sort) |
| Automations | **Tag added** and **Tag removed** triggers, tag rules in conditions, waits, goals and exits | **Score changed** trigger with a threshold, score rules in conditions |

## Tags

Tags are stored in lowercase, with spaces trimmed and runs of spaces collapsed, so `VIP`, `vip ` and `Vip` are the same tag. A tag can be up to 64 characters, and a contact can have any number of them.

- **On a contact:** open the contact, and in **Tags** type a tag and press Enter or a comma to add it, or select **×** on a tag to remove it. Suggestions come from the tags already used in the workspace.
- **New contacts:** **Add contact** has a **Tags** field.
- **Contacts list:** the **Tags** column shows the first three tags. The **All tags** filter in the toolbar lists the workspace's tags with how many contacts have each; pick one or more to show contacts with any of them.

Every change sends a `contact.updated` event with the new `tags` and the old ones in `previous.tags`. Webhooks subscribed to `contact.updated` get it, and it starts **Tag added** and **Tag removed** [triggers](/docs/automations/triggers/#tag-added-and-tag-removed).

### Tags with the API

| Do | Request |
| --- | --- |
| Add tags | [`POST /v2/contacts/{id}/tags`](/docs/api-reference/contacts/add-tags/) with `{ "tags": ["customer"] }` |
| Remove tags | [`DELETE /v2/contacts/{id}/tags`](/docs/api-reference/contacts/remove-tags/) with `{ "tags": ["trial"] }` |
| Replace all tags | [Update a contact](/docs/api-reference/contacts/update/) with `tags`, or change some with `add_tags` and `remove_tags` |
| Tag a new contact | [Create a contact](/docs/api-reference/contacts/create/) with `tags` |
| Find contacts by tag | [List contacts](/docs/api-reference/contacts/list/) with `filter[tag]=customer` (comma-separate several for any of them) |
| List the workspace's tags | [`GET /v2/contacts/tags`](/docs/api-reference/contacts/list-tags/) |

`{id}` is the contact ID or email address.

```bash
curl https://api.emailit.com/v2/contacts/ada@example.com/tags \
  -X POST \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "tags": ["customer"] }'
```

## Lead score

The score starts at 0 and can go negative. On the contact page, **Lead score** shows it; enter points and select **Add**, **Subtract** or **Set**. The contacts list has a sortable **Score** column.

Scores are usually changed by automations: add an **Update score** step after the actions that matter, for example `+10` in a **Wait until Link clicked** branch or `+20` when a form is submitted, and `-5` when a reminder goes unanswered. Use the score in a **Score changed** trigger with **Crosses** set, which starts once when a lead reaches the threshold, and in conditions such as "**Lead score** is at least `50`".

Every change sends `contact.updated` with `score` and `previous.score`.

[Segments](/docs/segments/) (alpha) can filter on both: **Tags** has any of, has all of or has none of, and **Lead score** is at least, at most or between. Tracked segments pick up tag and score changes like any other contact change.

With the API, [`POST /v2/contacts/{id}/score`](/docs/api-reference/contacts/score/) changes it atomically, so parallel updates don't overwrite each other:

```bash
curl https://api.emailit.com/v2/contacts/con_2kq8Vt4xLm7Rz/score \
  -X POST \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "operation": "add", "value": 10 }'
```

`operation` is `add` (default), `subtract` or `set`. You can also set `score` when you create or update a contact, and filter the list with `filter[score][gte]` and `filter[score][lte]`.

## Sync your CRM or app

Tags, the score and [custom fields](/docs/contacts/custom-fields/) are how your other systems steer automations. When your CRM or shop updates a contact through the API, the change sends `contact.updated`, and automations react within seconds:

| In your system | Update the contact with | In automations |
| --- | --- | --- |
| A deal is won, an order is paid | Tag `customer`, or a `purchased` custom field set to `true` | Exit conditions on sales sequences, **Tag added** to start onboarding |
| The lifecycle stage changes | A Select custom field `lifecycle_stage` | **Contact updated** with **Field that changed**, conditions on the stage |
| A rep is assigned | A custom field `account_manager_email` | **Reply to** `{{cf.account_manager_email}}` on **Send email** |
| Product usage | `POST /v2/contacts/{id}/score` | **Score changed** with a threshold |

## Related

  - [Custom fields](/docs/contacts/custom-fields/): Typed data on each contact.
  - [Exit conditions and goals](/docs/automations/exits-and-goals/): Use tags to end or move runs.

---
Source: https://emailit.com/docs/contacts/tags-and-score/