> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sequenzy.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Tags
> Segment subscribers and trigger automations with tags
# Tags
Tags are labels that help you organize, segment, and automate interactions with your subscribers. They're one of the most powerful features in Sequenzy.
## What Are Tags?
Tags are simple string labels attached to subscribers. Each subscriber can have multiple tags, and tags can be added or removed at any time.
```json theme={null}
{
"email": "user@example.com",
"tags": ["customer", "pro-plan", "newsletter", "webinar-attendee"]
}
```
## Why Use Tags?
### 1. Segmentation
Target specific groups in campaigns:
* Send product updates to `customer` tagged subscribers
* Exclude `churned` subscribers from promotional emails
* Target `trial` users with conversion campaigns
### 2. Automation Triggers
Start sequences when tags are added:
* When `customer` tag is added → Start onboarding sequence
* When `churned` tag is added → Start win-back sequence
* When `enterprise` tag is added → Notify sales team
### 3. Personalization
Customize email content by using tags in campaign targeting, automation
branches, or conditional display rules in the email editor. For raw HTML
templates, sync the value you need into a subscriber custom attribute and guard
the section with a simple conditional:
```html theme={null}
{{#if subscriber.isCustomer}}
Thanks for being a valued customer!
{{else}}
Ready to upgrade? Check out our plans.
{{/if}}
```
### 4. Analytics
Track subscriber segments over time:
* How many `trial` users convert to `customer`?
* What's the churn rate for `pro-plan` vs `starter-plan`?
## System Tags
Sequenzy includes built-in system tags for common use cases:
| Tag | Description | Auto-Applied |
| ----------- | ---------------------- | -------------- |
| `lead` | Potential customer | Manual |
| `customer` | Paying customer | Via sync rules |
| `trial` | In trial period | Via sync rules |
| `active` | Active subscription | Via sync rules |
| `cancelled` | Cancelled subscription | Via sync rules |
| `churned` | Churned customer | Via sync rules |
| `past-due` | Payment failed | Via sync rules |
| `refunded` | Received refund | Via sync rules |
| `inactive` | No recent activity | Manual |
System tags can be automatically applied through sync rules when connected to
payment providers like Stripe.
## Tag Normalization
Tags are automatically normalized when created:
* Converted to lowercase
* Spaces replaced with hyphens
* Special characters removed
```
"Pro Customer" → "pro-customer"
"VIP_User" → "vip-user"
"Newsletter!" → "newsletter"
```
## Adding Tags
### Single Tag
```bash theme={null}
curl -X POST "https://api.sequenzy.com/api/v1/subscribers/tags" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"email": "user@example.com",
"tag": "customer"
}'
```
### Multiple Tags (Bulk)
```bash theme={null}
curl -X POST "https://api.sequenzy.com/api/v1/subscribers/tags/bulk" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"email": "user@example.com",
"tags": ["customer", "pro-plan", "2024-cohort"]
}'
```
### Auto-Creation
When you add a tag, Sequenzy automatically:
1. Creates the subscriber if they don't exist
2. Creates the tag definition if it doesn't exist
3. Adds the tag to the subscriber
This makes integration seamless—no pre-configuration required.
## Removing Tags
Tags can be removed through:
1. **Dashboard** - Manual removal in subscriber profile
2. **Sequences** - "Remove Tag" action in automations
3. **Sync Rules** - Automatic removal when events occur
## Using Tags in Sequences
### Trigger: When Tag Added
Start a sequence when a subscriber receives a tag:
```
Trigger: contact_added_tag "customer"
│
▼
┌─────────────────┐
│ Welcome Email │
└─────────────────┘
│
▼
┌─────────────────┐
│ Wait 3 days │
└─────────────────┘
│
▼
┌─────────────────┐
│ Onboarding Tips │
└─────────────────┘
```
### Action: Add/Remove Tags
Modify tags during sequence execution:
```
┌─────────────────┐
│ Send Upgrade │
│ Offer Email │
└─────────────────┘
│
▼
┌─────────────────┐
│ Wait for Event │
│ "purchase" │
│ Timeout: 7 days │
└─────────────────┘
│
├── Event received ────────────┐
│ │
▼ ▼
┌─────────────────┐ ┌─────────────────┐
│ Add tag: │ │ Add tag: │
│ "converted" │ │ "offer-expired" │
└─────────────────┘ └─────────────────┘
```
### Condition: Has Tag
Branch logic based on tags:
```
┌─────────────────────┐
│ Condition: │
│ has_tag "customer" │
└─────────────────────┘
│
┌────┴────┐
│ │
Yes No
│ │
▼ ▼
┌─────────┐ ┌─────────┐
│ Upsell │ │ Convert │
│ Email │ │ Email │
└─────────┘ └─────────┘
```
## Using Tags in Campaigns
### Filter by Tags
When creating a campaign, filter recipients:
**Include subscribers with tags:**
* `customer` AND `active`
**Exclude subscribers with tags:**
* `churned` OR `unsubscribed`
### Example: Feature Announcement
Target active customers on pro plan:
```
Recipients: All subscribers
Filters:
- tags contains "customer"
- tags contains "pro-plan"
- tags not_contains "churned"
```
## Dashboard Visibility
In **Settings → Tags**, Sequenzy now shows:
* How many unique contacts were tagged with each tag in the last 24 hours
* Which active sequences currently trigger when that tag is added
* Which paused sequences would trigger if you reactivate them
You can also see the same sequence-trigger context on a subscriber's activity timeline when a tag is added, which helps you confirm whether a tag actually entered the right automation.
## Sync Rules
Sync rules automatically manage tags based on events. When an event occurs, specified tags are added and removed.
Configure automatic tagging based on events
### Default Sync Rules
| Event | Tags Added | Tags Removed |
| ---------------------- | ----------- | ------------------------------------------ |
| `saas.purchase` | `customer` | `lead`, `past-due`, `cancelled`, `churned` |
| `saas.churn` | `churned` | `customer`, `cancelled`, `past-due` |
| `saas.cancelled` | `cancelled` | `customer` |
| `saas.payment_failed` | `past-due` | — |
| `saas.refund` | `refunded` | — |
| `saas.trial_started` | `trial` | `lead` |
| `saas.trial_ended` | — | `trial` |
| `saas.trial_cancelled` | `cancelled` | — |
## Best Practices
### 1. Use Descriptive Names
```
✓ "webinar-jan-2024-attendee"
✓ "ebook-marketing-guide-downloaded"
✓ "pro-plan-annual"
✗ "tag1"
✗ "promo"
✗ "temp"
```
### 2. Create a Tagging Strategy
Define your tag taxonomy before implementation:
**Lifecycle tags:**
* `lead`, `trial`, `customer`, `churned`
**Plan tags:**
* `free-plan`, `starter-plan`, `pro-plan`, `enterprise-plan`
**Behavior tags:**
* `email-opened-30d`, `highly-engaged`, `at-risk`
**Source tags:**
* `source-organic`, `source-paid`, `source-referral`
### 3. Avoid Tag Proliferation
Too many tags become unmanageable. Consolidate similar tags:
```
✗ "clicked-email-jan", "clicked-email-feb", "clicked-email-mar"
✓ "email-engaged" (reset monthly)
✗ "purchased-product-a", "purchased-product-b", "purchased-product-c"
✓ "customer" + customAttribute: purchasedProducts
```
### 4. Use Events for Temporary States
For actions that happen multiple times, use events instead of tags:
```
✗ Tag: "viewed-pricing-page" (adds up over time)
✓ Event: "page_viewed" with properties: { page: "pricing" }
```
### 5. Document Your Tags
Maintain a reference of what each tag means and how it's applied:
| Tag | Description | Applied By |
| ------------ | ------------------------ | ------------------------ |
| `customer` | Has paid subscription | Sync rule: saas.purchase |
| `enterprise` | Enterprise plan customer | Manual |
| `newsletter` | Subscribed to newsletter | Signup form |
## Related
Trigger tag changes with events
Automate tagging based on events
Use tags to trigger and control flows
Add tags via API