Managing Contacts - Nitrosend

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

Importing contacts

Go to 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.

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.

You can also add contacts via the API:

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

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

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

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:

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:

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)

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.

{
  "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 for a full prompt-to-result walkthrough.

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

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.