# Managing Contacts {#managing-contacts}


Contacts are the people you send messages to. Each contact can have an email address, phone number, or both.

Keep evidence that recipients agreed to receive your marketing. Importing an
address or a **Subscribed** status does not itself prove permission. Preserve
opt-outs and suppressions when migrating a list; do not use an import or provider
switch to work around them. See [sender requirements](https://docs.nitrosend.com/guides/microsoft-delivery.md).


## Importing contacts {#importing-contacts}


Go to **Contacts > Import** ([app.nitrosend.com/my/contacts/import](https://app.nitrosend.com/my/contacts/import)) to upload a CSV file. Map your columns to contact fields during import.

Imports run in the background and show live progress while rows are processed. You can leave the page and return to the progress tray later.

Imports start no flows unless you turn on **Start flows** under Destination lists. With it on, contacts the import creates enter the live New contact flows they match, and new list members enter that list's live Add to list flows. With it off, the import summary names any live flows the import didn't start. Unsubscribe and block imports can't start flows.

You can also connect Mailchimp from **Integrations** to migrate audiences and members directly into Nitrosend. Mailchimp contacts keep their source metadata, and only Mailchimp members with `subscribed` status are opted in for email in Nitrosend.

Editing a contact or importing it again preserves its existing subscription. Contacts who have unsubscribed or been suppressed remain protected when an integration syncs again.

You can also add contacts via the API:

```bash
curl -X POST https://api.nitrosend.com/v1/my/contacts \
  -H "Authorization: Bearer nskey_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "email": "jane@example.com",
    "first_name": "Jane",
    "last_name": "Doe"
  }'
```


## Contact lists {#contact-lists}


Organize contacts into lists for targeted sending. A contact can belong to multiple lists.


## Saved views {#saved-views}


Use saved views to keep useful contact-table setups: search terms, filters, visible columns, and sort order. Saved views are helpful for day-to-day operations such as "recent imports", "VIPs with no recent clicks", or "contacts needing cleanup".

If the same rules should become an audience for campaigns or flow conditions, create a segment instead.


## Tags {#tags}


Tags are free-form string labels (e.g. `vip`, `newsletter`, `trial`) you attach to contacts for segmentation and targeting. A contact can have any number of tags. Tags are stored as an array of strings under the reserved `tags` key on each contact's `data` object.

Any tag string you use with a contact — via the REST API, the MCP tool, or the dashboard — is created automatically on first use. You can manage tags programmatically in two ways:


### Via the REST API {#via-the-rest-api}


Set the full list of tags on a contact by writing to `data.tags`. You can do this at creation time in the `POST /v1/my/contacts` body, or on an existing contact with `PATCH`:

```bash
curl -X PATCH https://api.nitrosend.com/v1/my/contacts/42 \
  -H "Authorization: Bearer nskey_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "data": { "tags": ["vip", "newsletter"] }
  }'
```

Filter contacts by a single tag with the `tag` query parameter:

```bash
curl -H "Authorization: Bearer nskey_live_..." \
  "https://api.nitrosend.com/v1/my/contacts?tag=vip"
```



> [!WARNING]
> PATCHing the `data` field **replaces the entire `data` object**, not just the keys you send. If the contact has other custom fields (e.g. `data.plan`, `data.apollo`), sending `{ "data": { "tags": [...] } }` will wipe them.
>
> To add or remove tags safely via REST, `GET /v1/my/contacts/{id}` first, merge your changes into the existing `data` hash, then `PATCH` the full merged object back. For add/remove semantics across many contacts in one call — without the read-modify-write dance — use the MCP tool below.




### Via the MCP tool (agents) {#via-the-mcp-tool-agents}


When an AI agent is managing contacts on a user's behalf, use the `nitro_manage_audience` tool with the `bulk_tag` operation. It supports `add`, `remove`, and `set` semantics across many contacts in one call — no read-modify-write dance.

```json
{
  "operation": "bulk_tag",
  "params": {
    "contact_ids": [1, 2, 3],
    "tags": ["vip", "newsletter"],
    "tag_action": "add"
  }
}
```

- **`tag_action: "add"`** (default) — merges the given tags into each contact's existing tags, deduplicated.
- **`tag_action: "remove"`** — removes the given tags from each contact; leaves other tags untouched.
- **`tag_action: "set"`** — replaces the entire tag list on each contact with the given tags.

`contact_ids` is required — omit it and the call fails rather than silently tagging every contact in the brand. Pass `dry_run: true` alongside to preview the affected `contact_count` without persisting.

See [Example Workflows](https://docs.nitrosend.com/guides/mcp-examples.md#example-4-bulk-tag-contacts) for a full prompt-to-result walkthrough.


## Segments {#segments}


Segments are dynamic groups defined by conditions (e.g., "subscribed in the last 30 days" or "opened an email this week"). Unlike lists, segments update automatically as contacts match or stop matching the criteria.

The segment builder supports profile, list membership, tag, custom-field, engagement, deliverability, and event-history filters. Tags are one of the available segment filters — use the `contact_tag` filter name with the `cont` (contains) predicate to build tag-based segments, e.g. `{ name: "contact_tag", predicate: "cont", value: "vip" }`.


## Contact activity {#contact-activity}


Open a contact to review their activity timeline. The timeline brings sends, opens, clicks, unsubscribes, bounces, complaints, list changes, and custom events together so you can understand recent behavior before sending again.
