Skip to main content

​
Subscribers

Subscribers are the core of Sequenzy. They represent contacts in your email marketing database—people who receive your campaigns, transactional emails, and automated sequences.

​
Subscriber Data Model

Each subscriber has the following properties:
PropertyTypeDescription
emailstringUnique email address (required)
firstNamestringFirst name
lastNamestringLast name
statusenumCurrent status: active, unsubscribed, bounced
tagsstring[]Array of tag names attached to subscriber
customAttributesobjectFlexible key-value store for custom data
createdAtdatetimeWhen the subscriber was created
updatedAtdatetimeWhen the subscriber was last modified

​
Subscriber Status

Subscribers can have one of three statuses:

​
Active

The subscriber can receive emails. This is the default status when a subscriber is created. 
{ "status": "active" }

​
Unsubscribed

The subscriber has opted out. They will not receive campaigns or sequences, but may still receive transactional emails if required. 
{ "status": "unsubscribed" }

​
Bounced

The email address is invalid or unreachable. Sequenzy automatically updates this status when emails bounce. 
{ "status": "bounced" }
Never send marketing emails to unsubscribed or bounced subscribers. Sequenzy automatically filters them from campaigns.

​
Custom Attributes

Custom attributes allow you to store any data about subscribers. Use them for:
  • User IDs from your application
  • Subscription plans or tiers
  • Geographic information
  • Purchase history
  • Preferences
{
  "customAttributes": {
    "userId": "usr_12345",
    "plan": "pro",
    "company": "Acme Inc",
    "industry": "technology",
    "mrr": 99.99,
    "signupSource": "google-ads"
  }
}

​
Using Attributes in Emails

Custom attributes are available as template variables: 
<p>Hi {{FIRST_NAME}},</p>
<p>Your current plan: {{plan}}</p>
<p>Company: {{company}}</p>

​
Using Attributes in Conditions

Filter campaigns and create sequence conditions based on attributes:
  • field_equals: Check exact match
  • field_contains: Check if value contains string
  • field_greater_than: Numeric comparison
  • field_less_than: Numeric comparison

​
Tags

Tags are labels that categorize subscribers. They’re essential for:
  1. Segmentation - Target campaigns to specific groups
  2. Automation Triggers - Start sequences when tags are added
  3. Filtering - Find subscribers with specific characteristics

Learn More About Tags

Deep dive into tag management and best practices

​
Subscriber Lifecycle

                    ┌─────────────────┐
                    │     Created     │
                    │   (via API or   │
                    │    dashboard)   │
                    └────────┬────────┘
                             │
                             ▼
                    ┌─────────────────┐
         ┌─────────│     Active      │──────────┐
         │         └────────┬────────┘          │
         │                  │                   │
    Unsubscribe        Hard Bounce         Sequences
         │                  │              Campaigns
         ▼                  ▼             Transactional
┌─────────────────┐ ┌─────────────────┐         │
│  Unsubscribed   │ │     Bounced     │         │
└─────────────────┘ └─────────────────┘         │
         │                  │                   │
         └──────────────────┼───────────────────┘
                            │
                            ▼
                   ┌─────────────────┐
                   │    Tracking     │
                   │ (opens, clicks) │
                   └─────────────────┘

​
Creating Subscribers

​
Via API

curl -X POST "https://api.sequenzy.com/api/v1/subscribers" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "firstName": "Jane",
    "lastName": "Smith",
    "tags": ["newsletter", "free-tier"],
    "customAttributes": {
      "source": "landing-page",
      "referrer": "google"
    }
  }'

​
Auto-Creation

Subscribers are automatically created when you:
  • Add a tag to a non-existent email
  • Trigger an event for a non-existent email
  • Send a transactional email to a non-existent email
This makes integration easier—you don’t need to create subscribers before interacting with them.

​
Updating Subscribers

Use PATCH to update subscriber data: 
curl -X PATCH "https://api.sequenzy.com/api/v1/subscribers/[email protected]" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Janet",
    "customAttributes": {
      "plan": "pro",
      "upgradedAt": "2024-01-15"
    }
  }'
Custom attributes are merged, not replaced. To remove an attribute, set it to null.

​
Filtering Subscribers

When sending campaigns, you can filter subscribers by:
FilterOperatorsExample
Statusis, is_notStatus is “active”
Tagscontains, not_containsTags contains “customer”
Emailcontains, not_containsEmail contains “@company.com”
Date Addedless_than, more_thanAdded more than 7 days ago
Namecontains, not_containsFirst name contains “John”

​
Best Practices

​
1. Capture Data at Sign-up

Collect custom attributes when users first sign up: 
await sequenzy.subscribers.create({
  email: user.email,
  firstName: user.firstName,
  customAttributes: {
    userId: user.id,
    signupDate: new Date().toISOString(),
    source: utm_source,
    medium: utm_medium,
    campaign: utm_campaign,
  },
});

​
2. Keep Attributes Updated

Sync changes from your app to Sequenzy: 
// When user updates profile
await sequenzy.subscribers.update(user.email, {
  firstName: newFirstName,
  customAttributes: {
    timezone: newTimezone,
    language: newLanguage,
  },
});

​
3. Use Tags for Segments

Tags are more flexible than custom attributes for segmentation: 
// Good: Use tags for states
await sequenzy.subscribers.addTag(email, "customer");

// Avoid: Using boolean attributes for states
await sequenzy.subscribers.update(email, {
  customAttributes: { isCustomer: true }, // Less flexible
});

​
4. Clean Your List

Regularly remove bounced and unengaged subscribers:
  • Remove hard bounces immediately
  • Consider removing subscribers who haven’t opened in 6+ months
  • Use re-engagement campaigns before removing inactive subscribers

Tags

Learn about tagging and segmentation

Events

Track subscriber actions with events

Sequences

Automate emails based on subscriber data

API Reference

Subscribers API documentation