> ## Documentation Index
> Fetch the complete documentation index at: https://docs.politicalcomms.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Triggers that fire when a contact is tagged

> Send a text or email to each person the moment they are given a tag. Who it starts with, the confirmation when you tag many people at once, who is and is not texted, and the API.

A **tag trigger** sends a message to a person when they are given a [tag](https://docs.politicalcomms.com/help/tags.md). It is one of the trigger choices on a [triggered text project or email campaign](https://docs.politicalcomms.com/help/triggered-sends.md): choose **When a contact is tagged**, pick one or more of your tags (up to 20), and set when the message goes (right away, after a wait, or the next day at a time you set).

Only your own tags can be chosen. Activity, such as **Clicked**, is not a tag and cannot start a trigger. A tagged phone number starts a text project, and a tagged email address starts an email campaign.

## Once per person

A person is sent a triggered project or campaign once. Tagging someone who already has the tag does nothing. Taking the tag off and putting it back does not send again.

## Who it starts with

The first time you start a tag-triggered project or campaign, it asks one question.

| Choice | What happens |
| - | - |
| **Everyone who has the tag now, plus everyone tagged from now on** | Everyone who carries the tag today is sent the message, in the background, and so is everyone tagged later. The dialog shows how many people that is and an estimated cost before you start. |
| **Only people tagged from now on** | Nobody is messaged until someone is tagged. |

You must choose; there is no default. Resuming a paused project or campaign does not ask again.

Once a tag trigger has started, you cannot point it at other tags, or turn it into another kind of trigger. End it and create a new one instead. Until it starts you can change anything.

## Tagging many people at once

Tagging people into a tag that a live triggered project or campaign listens for **sends messages**, so you are asked before it happens. When you tag in the dashboard (a person, a selection, a whole list, an upload, or a rule), a confirmation names the projects and campaigns that would start, how many people would be reached, and an estimated cost. Each message is charged as it sends.

* **Tag and send.** People who newly get the tag are sent the message. Anyone already sent it is not sent it again.
* **Tag without sending.** The tag is applied and nobody is messaged. People tagged this way are not sent the message later, because they already have the tag.
* **Cancel.** Nothing happens.

## Who is and is not texted

A tag says who to send to, and a list row says the person can be sent to. For a text project:

* A tagged phone number on a list the project can use is texted, and the message uses that list row's merge fields, such as `{first_name}`.
* A tagged phone number on no list at all is texted too, with your merge-field defaults in place of anything missing.
* A tagged phone number whose only list rows belong to another brand, toll-free number or short code is **not** texted. The project's report counts it as skipped, and it has not used its one entry.
* A phone number that has opted out is never texted, and an email address that has unsubscribed or is suppressed is never emailed.

## Pausing, ending, and deleting a tag

A tag cannot be deleted while a triggered project or campaign that is not finished, archived or deleted listens for it. End that project or campaign first.

## Over the API

* A trigger is `{"source": "tag", "tag": {"tag_ids": ["<tag id>"]}, "start": "immediate"}`, on `POST /v1/projects` (type `triggered`) or `POST /v1/email/campaigns`. `start` is `immediate` or `next_day`; `next_day` needs the time zone and time of day in the same request. See [Triggered texts and emails](https://docs.politicalcomms.com/help/triggered-sends.md).
* Start it with `POST /v1/projects/{id}/start`, or `POST /v1/email/campaigns/{id}/schedule` for email, with `{"audience": "current_and_new"}` or `{"audience": "new_only"}`. It is required for a tag trigger's first start, and any other project or campaign refuses it.
* `GET /v1/tags` shows `live_triggers` on every tag: the triggered projects and campaigns that listen for it, each with its `id`, `name` and `channel`. It is empty when none do.
* `POST /v1/tags/{id}/contacts` and `POST /v1/tags/contacts` take `fire_triggers`. With phone numbers or email addresses (`identifiers`) it defaults to `true`; with a `contact_list_id` it defaults to `false`. `POST /v1/contact-lists/import` takes it too, default `false`. When the tag has live triggers, a synchronous response carries `triggers.entered`, the number of people entered; a queued list or import echoes `fire_triggers`. Removing a tag from contacts takes no `fire_triggers`.

> [!WARNING]
>
> Tagging into a tag that has `live_triggers` messages people. Check `live_triggers` on `GET /v1/tags` first, and send `fire_triggers: true` for a list or an import only when you mean to message everyone newly tagged.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.