Guides

Managing Contacts

Import, organize, and segment your audience

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.

Importing contacts

Go to Contacts > Import (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:

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.