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

# Triggered texts and emails

> Send a text or email to each person as something happens: a donation, a link click, a reply, a contact being tagged, or a call from your CRM. Triggers, when the message goes, merge fields, and worked examples.

A **triggered** text project or email campaign has no contact list. People arrive one at a time, when its **trigger** fires, and each one gets its one message, right away, after a wait, or the next day at a time you set. It stays active until you pause or end it, so you set it up once and it keeps working.

Use it for a thank-you after a gift, a welcome to everyone you tag as a new volunteer, a message to someone who clicked a link, or a message to someone your CRM just added. A triggered text project can also send [follow-ups](https://docs.politicalcomms.com/help/follow-ups.md) after its first message.

## What can be a trigger

Every triggered project or campaign has one of four trigger sources.

| Source | The message goes to someone when |
| - | - |
| **A donation** | A gift comes in through a connected WinRed or Anedot list. |
| **Something happens in a project or campaign** | A person clicks a link in a text, replies to a text, opens an email, clicks a link in an email, or replies to an email, in the projects or campaigns you choose. |
| **A contact is tagged** | A contact is given one of the [tags](https://docs.politicalcomms.com/help/tags.md) you choose: by hand, by an upload, by a rule, or over the API. See [Triggers that fire when a contact is tagged](https://docs.politicalcomms.com/help/tag-triggers.md). |
| **An API call or webhook** | Your CRM, a form tool, or an automation adds one recipient with the API or a webhook URL. |

### Donation triggers

Choose which connected lists to listen to, then narrow by any of these. A gift must match everything you set.

* **Donor.** Any donor, a **first-time** donor (no earlier gift on record for your organization), or a **returning** donor.
* **Gift.** Any gift, a **one-time** gift, or a **recurring** gift.
* **Amount.** A minimum, a maximum, or both, in dollars, inclusive.
* **Page names** and **source codes.** Match a specific donation page or code. Matching ignores capitalization and must be exact. Leave empty for any.

### Event triggers

Pick the event, then whether it counts in **any** project (or campaign) or only the ones you choose. Choosing **any** never includes another triggered project or campaign, so two triggered items cannot set each other off in a loop. For email clicks you can also name one link, so only a click on that link counts.

Text events can follow email events and the reverse. A text project listening to an email event sends only when the person's record has a phone number; an email campaign listening to a text event sends only when it has an email address.

> [!NOTE]
>
> Email opens are approximate. Some mail apps hide opens, so an open trigger misses people who did read the email. A click or reply is a stronger signal.

## Timing

Choose when the first message goes. In the trigger's **Send** choice:

* **Right away.** The message goes as soon as the trigger fires.
* **After a wait.** Send up to 30 days (43,200 minutes) after the trigger fires.
* **The next day at...** Send on the calendar day after the trigger fired, at the time of day and in the time zone you set (Eastern, Central, Mountain, Pacific, Alaska, or Hawaii). It has no wait of its own: a gift at 9 PM Tuesday is thanked Wednesday at the time you chose. Over the API this is `start: "next_day"` with the project's `scheduled_timezone` and `sequence_send_time` (an email campaign uses `timezone` and `sequence_send_time`).
* **The overnight hold for texts.** A text that comes due between 10 PM and 8 AM in the recipient's time zone, worked out from their area code, is held until 8 AM. This only ever moves a text later, including one set for the next day at a time you chose. Email has no such hold.
* **Opted-out and suppressed.** An opted-out phone number or a suppressed email address is never sent to. These people are counted as skipped in the report.

## Once per person

A person is sent a triggered project or campaign **once**. A second donation from the same person does not send them a second thank-you, and a second trigger for the same person is answered as already entered, even after their follow-ups have finished. If you want to reach someone again, send a different project or campaign.

## Merge fields

Fields that arrive with a person work as merge tags in your message, such as `{first_name}`.

* **Donations** carry `first_name`, `last_name`, `email`, `address`, `address_2`, `city`, `state`, `zip`, `employer`, `occupation`, `amount`, `page_name`, and `source_code`.
* **API and webhook recipients** carry whatever fields you send with them, up to 50.

The fields are stored on the recipient and show up in reports, exports, and as `contact.custom_fields` in your [outbound webhooks](https://docs.politicalcomms.com/api-reference/webhooks/events.md). Your outbound webhook events fire for triggered sends exactly as they do for any other send.

## Set one up

**Texts.** Create a project, choose the type **Triggered**, write the message, and choose the trigger and its timing. A triggered project has no contact list. Send a test, then **Start**. Triggered projects follow the same registration and sending rules as any other text. To add follow-ups, use the **Follow-ups** section: see [Follow-ups](https://docs.politicalcomms.com/help/follow-ups.md).

**Email.** Create a campaign, choose the type **Triggered**, pick the sender and template, and choose the trigger and its timing. A triggered campaign has no lists and no send window. It can have [follow-ups](https://docs.politicalcomms.com/help/follow-ups.md#email-follow-ups): each person gets each one a number of whole days (at least one) after their own previous email. Send a test, then **Start**. Triggered email sends are not held by the frequency cap that limits broadcasts.

Both can also be created over the API: send `type: "triggered"` and a `trigger` to `POST /v1/projects`, or a `trigger` in place of `list_ids` to `POST /v1/email/campaigns`. The type of a project or campaign is fixed when you create it. A trigger that listens for a tag asks who it sends to when you first start it: see [Triggers that fire when a contact is tagged](https://docs.politicalcomms.com/help/tag-triggers.md).

**Over the API.** Triggered projects use `POST /v1/projects` with `"type": "triggered"`, then `/test`, `/start`, `/recipients`, `/hook`, `/end`. See the [API reference](https://docs.politicalcomms.com/api-reference/introduction.md).

## Pausing and ending

| | Pause | End |
| - | - | - |
| What happens | It stops adding people. Anyone already waiting is held. | It stops for good. Anyone still waiting is **not** sent. |
| New recipients | Refused, not queued. An API or webhook call to a paused item gets an error. | Refused. |
| Can it come back | Yes. Resume it, and people who were waiting are sent on their schedule. Over the API, pause a triggered email campaign with `POST /v1/email/campaigns/{id}/pause` and resume it with `POST /v1/email/campaigns/{id}/resume`. | No. Create a new triggered project or campaign to keep going. |

Pause to fix a typo or hold during a news cycle. End when the program is over. Ending settles anything still on its way out: texts that have not left yet are not sent and their cost is returned, so a project can show as paused for a few seconds before it shows as completed.

Triggered texts go to US numbers only. A number in another country, including Canada, is refused when it is added, because the overnight hold is worked out from a US area code.

## Reporting

A triggered project's report shows who has been sent to, who is **waiting** (entered, not sent yet because of a delay, an overnight hold, or a pause), and who was **skipped**, with the reason, such as opted out. When it has follow-ups, it also shows who left them and why: replied, clicked, or opted out. Waiting and skipped counts also come back from the API on `GET /v1/projects/stats`.

The export has one row per person with the fields they arrived with and when and why they entered. People who never got a message show **Not sent (waiting)**, **Not sent (skipped: reason)**, or **Not sent (cancelled)**.

## Worked examples

### Thank a first-time WinRed donor by text

1. Connect your WinRed list under **Assets > Lists** if you have not already.
2. Create a project, choose **Triggered**, and write: `Thank you, {first_name}, for your first gift to the campaign. It means more than you know.`
3. For the trigger, choose **A donation**, pick your WinRed list, and set **Donor** to **First-time**. Leave **Gift** on **Any**.
4. Set a delay of 15 minutes so the thank-you does not land the second the page closes.
5. Send a test, then **Start**.

A first-time donor who gives at 9 PM is thanked at 8 AM the next morning in their time zone, because of the overnight hold.

### Email someone who clicked a link in a text

1. Create an email campaign of type **Triggered**. For its trigger choose **Something happens in a project or campaign**, the event **A link is clicked in a text**, and the text project that carries the link. Over the API that is source `event`, event `text_link_click`, with no `list_ids`.
2. Write the follow-up and use `{first_name}` if the person's record has it.
3. Set a delay if you want it to arrive later, send a test, and start it.

Someone is emailed only if their record carries an email address, and only once.

```json theme={null}
{
  "source": "event",
  "event": {
    "event": "text_link_click",
    "sources": { "ids": ["8a3f5c7e-2d91-4b64-ae08-6f1c9d3e7b52"] }
  },
  "start": "immediate",
  "delay_minutes": 60
}
```

### Add a recipient from your CRM with the API

1. Create a triggered project with the source **An API call or webhook**, test it, and start it.
2. When your CRM records the event, call `POST /v1/projects/{id}/recipients` with the number and any fields:

```bash theme={null}
curl -X POST https://api.politicalcomms.com/v1/projects/$PROJECT_ID/recipients \
  -H "X-API-Key: $PC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phone_number": "+12025550141", "fields": {"first_name": "Ada"}, "occurrence_id": "crm-evt-123"}'
```

`202` means it is queued and tells you when it will send. `200` means this person or this `occurrence_id` was already entered, which is the normal answer to a retry. `409` means the project is paused or not started, or the person has opted out.

If your tool cannot set an API key, use the project's webhook URL instead: see [Inbound hook](https://docs.politicalcomms.com/api-reference/webhooks/inbound-hook.md), including Zapier and Make steps.


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