Skip to main content
A tag is a label on a contact, a phone number or an email address, inside one organization. Tags let you find the people you care about and send to them without building a list first. Nothing another organization tagged is ever shown to you.

Tags and activity

Tag names are unique within an organization, ignoring capitals, and run up to 64 characters. A tag may share a name with an activity, such as Clicked. Each contact shows its own activity as facts, with nothing to tag: Clicked 3 days ago, Responded 12 days ago, Donated 40 days ago, Sent to 2 days ago. The All contacts table shows the newest; a contact’s page shows them all.

Where you manage tags

Tags live under Assets > Lists, which has these tabs:
  • Lists. Every list you have. A list shows every member, searchable, with the tags each one carries, and you can tag everyone on the list at once.
  • All contacts. Everyone your organization has messaged or tagged, with search and a filter by tag. This is where the old People page now lives; see People.
  • Tags. Your tags, how many contacts carry them, and when they were created. Create, rename, or delete a tag. Activity is not listed here: it needs no tag.
A tag cannot be deleted while a scheduled, compiling, active, sending, or paused text project or email campaign uses it, or while a triggered project or campaign that is not finished listens for it. The page names the sends in the way; remove the tag from them or wait for them to finish. Deleting a tag removes it from drafts and finished sends.

Putting tags on contacts

  • By hand. Select people on All contacts, or choose Tag everyone on a list. If a triggered project or campaign listens for the tag, you are asked first whether to Tag and send or Tag without sending: see Triggers that fire when a contact is tagged. Tagging a whole list runs in the background, and the tag’s contact count updates when it finishes.
  • At upload. When you upload an audience list you can tag everyone in the file, or name a column of the file that holds each row’s tags. In that column, separate tags with commas, semicolons, or pipes. Tags that do not exist yet are created. A file can add up to 20 tags to everyone, and a column that would create more than 100 new tags fails the import. A do-not-contact file takes no tags.
  • By rule. The text and email segment builders can tag the contacts a rule matches instead of creating a new list. The tagging runs in the background, and the tag’s count shows the result when it finishes.
  • Over the API. POST /v1/tags/contacts with a tag name and phone numbers and email addresses, or a list. The tag is created if it is new. Phone numbers and email addresses are tagged at once; a whole list is tagged in the background. See the API.

Sending to tags

A text project (including a survey) and an email campaign each have three tag fields in their recipients. Each takes tags and activity: Activity works fastest as a filter: choose your lists, then pick the activity under Only contacts who…. As a source, each person it finds must be matched to a list row on their own; a text project refuses to start when more than 25,000 of them would each need a separate lookup, and its preview says how many are not yet counted. The same tag or activity cannot be a source and in Leave out contacts who… in the same send, nor in both Only contacts who… and Leave out contacts who…, because either would send to nobody it names. The recipient preview shows how many people the tags added and how many Only contacts who… left out.

Leaving people out is not an opt-out

Leave out contacts who… is a suppression: a choice you make for one send. Opt-outs and unsubscribes are compliance records: they always apply, to every send, and tagging or untagging someone never changes them. Removing a tag or activity from it does not bring back anyone who opted out.

A tagged contact still needs a list row

A tag says who to send to; a list row records that the person can be sent to. A tagged contact is only sent to through a list row the sender can use:
  • Text. The phone number must be on a live list that the project’s sender can use: a list that is not tied to a brand or number, or one tied to the project’s own brand, toll-free number, or short code. A tagged number on no such list is not texted, and the preview says how many.
  • Email. The address must be subscribed on a list the sending domain can use.
A contact you tagged but who is on no usable list is skipped, not sent to by guesswork. Add them to a list to include them. Triggered projects and campaigns take no tags as recipients, because their recipients come from the trigger. A trigger can listen for a tag instead: see Triggers that fire when a contact is tagged.

Editing a send’s tags

Changing the tags on a text project is a content edit, so the project returns to Awaiting test like any other edit. On an email campaign it invalidates the test send in the same way as editing its lists. See Campaigns and deliverability.

Over the API

Tag by name

The simplest way to tag is one call: POST /v1/tags/contacts with the tag’s name and either identifiers (up to 10,000 phone numbers or email addresses) or a contact_list_id. You do not need to create the tag first. If your organization has no tag with that name, the call creates it. Names are not case sensitive, so Donor and donor are the same tag. A name is always a tag you can add contacts to: Clicked is a tag of that name, never the activity.
With phone numbers and email addresses, the response carries the tag, created (true only when this call created the tag), added, and invalid. Check created: if you expected an existing tag and it is true, the name was probably misspelled and made a new tag. POST /v1/tags/contacts and POST /v1/tags/{id}/contacts also take fire_triggers. If a live triggered project or campaign listens for the tag, tagging sends to the people newly tagged, so check live_triggers on GET /v1/tags first. fire_triggers defaults to true with identifiers and false with a contact_list_id; a synchronous response carries triggers.entered. See Triggers that fire when a contact is tagged. DELETE /v1/tags/contacts takes the same body and removes the tag from those contacts. It never creates a tag, and a name with no tag returns not found. It needs an API key with the delete permission. With a contact_list_id, the whole list is tagged in the background. The call returns 202 with queued: true and a job_id, and no counts. The tag is still created right away. Do not wait for counts: read the tag’s member_count on GET /v1/tags after a while, and it updates when the job finishes. Sending the same Idempotency-Key again returns the same answer and queues nothing new. DELETE with a list works the same way. A list that is not yours, or an activity id named on a by-id call, is refused at once, before anything is queued.

Tag by id

POST and DELETE /v1/tags/{id}/contacts work the same way when you already hold a tag’s id. GET /v1/tags lists your tags with their ids, and the tag in a by-name response carries its id too. Projects and email campaigns still refer to tags by id, not by name: tag_ids, require_tag_ids, and suppression_tag_ids (up to 50 each) work on POST /v1/projects and PATCH /v1/projects/{id} (for broadcast and survey projects), and POST /v1/email/campaigns. A survey with neither a list nor a source tag is created as a draft, and an edit cannot leave a survey with neither. Get the ids from GET /v1/tags or from a by-name response. tag_ids, tag_names, and tags_column work on POST /v1/contact-lists/import. If that import fails, GET /v1/contact-lists/{id} says why in import.error.

All tag operations

Eight operations manage tags: list, create, rename, and delete tags, add or remove contacts by name, and add or remove contacts by id. A tag outside your key’s organizations behaves exactly like a tag that does not exist. See the Tags group in the API reference and the OpenAPI spec.