Skip to main content
Sequenzy subscribers dashboard with callouts showing how to add and open contacts
Subscribers are the core of Sequenzy. They represent contacts in your email marketing database: people who receive your campaigns, transactional emails, and automated sequences.

Create a campaign for a selected group

Apply filters, search or select contact rows to reveal Create campaign. Choose a template, existing email, blank draft or AI prompt. Every matching contact across pages is saved directly in the draft; list membership and existing sequence enrollments do not change. New matching contacts do not join automatically, and eligibility is checked again before sending. Saved lists and segments keep their existing campaign and sequence creation actions. You can also create a draft for a group through the API, CLI or MCP.

Subscriber Data Model

Sequenzy subscriber profile with callouts showing activity and custom attributes
Each subscriber has the following properties:

Phone-Only Contacts

A contact can exist with only a phone number and no email address - for example, an SMS-focused list uploaded from another platform. Phone-only contacts:
  • Can be created through the CSV import (map a phone column and leave email unmapped), the API, the CLI, and MCP
  • Are automatically excluded from email campaigns and skipped by sequence email steps
  • Receive SMS campaigns and sequence SMS steps normally once they have SMS consent
  • Deduplicate by phone number: importing the same phone again updates the existing contact instead of creating a duplicate

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.

Unsubscribed

The subscriber has opted out. They will not receive campaigns or sequences, but may still receive transactional emails if required.

Bounced

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

Double Opt-In

Double opt-in lets you require email confirmation before new signups become active subscribers. While confirmation is pending, Sequenzy stores the contact as unsubscribed, holds target list membership and signup tags, and sends a confirmation email. After the subscriber clicks the confirmation link, Sequenzy activates the subscriber, applies the held lists and tags, and triggers matching automations.

Double Opt-In

Learn how to enable confirmation emails for subscriber signups.

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
  • Dates and timestamps like signup time, renewal date, or latest checkout attempt

Attribute Types

Each attribute value keeps the JSON type you send: string, number, boolean, or a list of those. Keep the same type for an attribute across contacts so segment filters and conditions compare values consistently. Send zip codes, phone-like IDs and other values with leading zeros as strings, for example "zip": "02134", because a number drops the leading zero. In the dashboard, + add on a contact’s Attributes card lists the attributes your other contacts already have and fills in their type. Each attribute shows a type selector for switching between string, number and boolean. Automatic detection keeps values with leading zeros and numbers longer than 15 digits as strings. CSV imports in the dashboard use the same rule when they detect a column’s type, so a zip column stays text when any value has a leading zero. To see the names and types already in use, call List Subscriber Attributes, run sequenzy subscribers attributes, or use the list_subscriber_attributes MCP tool. In the CLI, --attr key=value always sends strings. Use --attrs-json on subscribers add and subscribers update for other types.

Using Attributes in Emails

Custom attributes are available as template variables:

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
Date and datetime attributes also work in these comparisons. If you send ISO date values like 2026-03-20 or full timestamps like 2026-03-19T10:56:03+00:00, Sequenzy stores them in a way that supports exact matches and before/after-style range filters.

Commerce Attributes

Commerce integrations can sync revenue and order metrics onto subscriber profiles. The subscriber table shows revenue metrics directly, including AOV when either aov or legacy averageOrderValue is present.
Older commerce data may include totalRevenue or averageOrderValue. Sequenzy treats totalRevenue as an ltv fallback and averageOrderValue as an aov fallback so subscriber views do not show duplicate cards for the same metric.

Purchased Products

Subscriber profiles show purchased products when Sequenzy has product-level purchase data.
  • Stripe purchased products come from Stripe payment history and product catalog data
  • Shopify and WooCommerce purchased products come from ecommerce.order_placed line items
  • Product cards can show image, name, provider, variant, quantity, price, and last purchase time when those fields are available
For Shopify and WooCommerce, make sure order events include lineItems[].providerProductId. Variant-level display and matching also uses lineItems[].providerVariantId.

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

Lists And Visibility

Subscriber lists can be either public or private.
  • Public lists appear on the hosted subscriber email preferences/unsubscribe page. Their names are subscriber-facing, and subscribers can subscribe or unsubscribe from them individually. List descriptions remain internal workspace metadata and are never shown on this public page.
  • Private lists are hidden by default. Enable Allow members to unsubscribe when you create or edit a private list to show its name only to existing members in preferences. Members can opt out, after which the list disappears. Global resubscribe does not rejoin private lists with this setting enabled; an authorized workspace user must add the member again. Other subscribers cannot discover or join it. Descriptions stay internal. Leaving a list does not cancel a paid membership or stop emails targeted through other lists.
New lists are public by default. When you create a public list, name it as a subscriber-facing category such as Newsletter or Product Updates. Internal cohort names and operational buckets are usually a better fit for private lists. If no lists are visible to the subscriber, the hosted page shows a single Unsubscribe button for the global opt-out instead of per-list toggles, and an already-unsubscribed visitor sees a Resubscribe option there. List privacy controls visibility in the preference center; it does not override a subscriber’s global unsubscribe. Choosing to unsubscribe from all email still unsubscribes the subscriber from every active list membership, including private lists. You can also set allowMemberUnsubscribe through the list API, sequenzy lists create|update --allow-member-unsubscribe (disable with --no-allow-member-unsubscribe), or the MCP create_list and update_list tools. Existing lists default to disabled.

Default Lists

Plenty of things create a contact without saying which list it belongs in: a form without list targeting, an API write that omits listIds, an event or tag action for an unknown address, a CSV import, and any integration that has no per-integration list targeting of its own. The Default Lists setting decides where those contacts land. Find it in the dashboard under Contacts -> Lists -> Default Lists. It is not under Settings. There are three modes, and they are genuinely different: The setting applies automatically when a write creates a contact, not on every write. An ordinary profile or attribute upsert for an active contact leaves their list memberships alone unless it names lists explicitly, so a background sync cannot pull long-standing contacts into a list created after they signed up. Explicit subscription and lifecycle reactivation flows are the exceptions: capture submissions (including forms, popups, landing pages, and connected-site forms) and a confirmed provider re-creation can reapply target or default lists so the returning contact actually rejoins them. Read and change it from the API, CLI, and MCP as well:
Over the API it is the defaultSubscriberListIds field on get company and update company; over MCP it is the same field on get_company and update_company. Changing it needs the companies:manage scope.
Check this setting before connecting a store, payment, or analytics integration. A provider without its own list targeting - Dodo Payments, PostHog, Polar, Paddle, WooCommerce - sends contacts created by live ingestion to whatever the workspace default points at. Payment-provider backfills do the same. PostHog history imports are an exception: contacts created by that import have no list memberships.If that is a lead-magnet or webinar list, a later campaign aimed at “the people who opted in” will reach the imported customers too.Changing the default only affects later writes. Nobody is moved or removed retroactively, so a list that has already been filled needs cleaning up with remove subscribers from a list or sequenzy lists remove-subscribers.

Subscriber Lifecycle

Creating Subscribers

Start on the Subscribers page. Select Add contacts, then choose whether to add contacts manually or import a CSV.
Sequenzy subscribers page with callouts showing manual contact creation and CSV import

Add Manually

Enter one or more email addresses or phone numbers, choose any lists and tags, and optionally enroll the new contacts in sequences.
Sequenzy manual contact dialog with callouts showing contact data, audience choices, and sequence enrollment

Import A CSV

For a larger batch, choose Add contacts → Import CSV, then upload a file or paste CSV data. Confirm the email or phone column, map any optional contact fields, and add tag or custom-attribute rules before previewing the import.
Sequenzy CSV subscriber import with callouts showing required and optional field mapping
CSV imports are validated contact by contact: you record the source and confirm permission, and each contact goes through validation and suppression handling. API, CLI, and MCP imports use the same contact-level validation.

Statuses from another platform

Exports from AWeber, Mailchimp, Kit, MailerLite, Brevo, ActiveCampaign and beehiiv include each contact’s status. The importer maps a column named like Status, Subscriber Status, Email Status, Subscription Status, State or Consent to the Status field, which you can change in the Field mapping step. The field only appears when your file has a status column. An Unsubscribe Date or unsubscribed_at column is picked up automatically. A filled unsubscribe date makes that row unsubscribed even when the file has no status column. Contacts who never confirmed their subscription in the other platform import as active. The preview shows how many contacts land in each status before you import. Unsubscribed and bounced contacts are kept on record but are never emailed, never enrolled in sequences and never sent a double opt-in email by the import. An active row never resubscribes a contact who already unsubscribed or bounced. With Merge or Overwrite, an unsubscribed or bounced row applies that status to an existing active contact; Skip leaves existing contacts as they are.

Reconciling An Import

Custom-attribute segment counts may take roughly 30–35 seconds, or longer when background processing is busy, to reflect imported updates. Attribute sync can still be pending after the import shows completed. Wait and recheck the segment count before using it to verify your imported audience. Every row an import excludes is accounted for. When an import finishes, the skipped-reason counts add up to the number of skipped rows, the failed-reason counts add up to the number of failed rows, and added + updated + skipped + failed equals the number of rows you submitted. The dashboard shows the reasons in the import banner’s issue list; the API, CLI, and MCP return the same counts on the import record. See Get Subscriber Import for the list of reasons.

Via API

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 marketing email (emailType: "marketing") through the transactional API
  • Capture a native Webflow form submission through the Webflow integration
This makes integration easier: you don’t need to create subscribers before interacting with them. Auto-created subscribers join whatever Default Lists is set to, unless the call targets lists explicitly.

Updating Subscribers

Use PATCH to update subscriber data:
By default, customAttributes replaces the existing public custom-attribute map. Add "customAttributesStrategy": "merge" to the PATCH body to retain unspecified existing keys while overwriting the keys you send.

Filtering Subscribers

Sequenzy segment builder with callouts showing templates and precise filters
When sending campaigns, you can filter subscribers by: Email is and is_not match the full address and ignore case, so use them for explicit allowlists and exclusions. Use contains for domain or substring matches like @company.com. For date filters, you can use:
  • Rolling relative values like 7 days ago, last week, or 3 days from now
  • Fixed dates like 2026-03-01 or Mar 1 2026
less_than means “within/after this point” and more_than means “before/older than this point”. Rolling values update automatically as time passes. Fixed dates stay fixed. If a custom attribute stores a date or timestamp, you can use the same values in attribute comparisons such as renewal_date < 3 days from now. Email provider detection runs in the background. We normalize major providers into stable buckets such as Google, Microsoft, and iCloud, so Gmail and Google Workspace filter together, Outlook/Hotmail/Microsoft 365 filter together, and dozens of regional providers like UKR.NET, Seznam, Onet, GMX, and Telenet can also be filtered directly.

Push Filters

Once you set up push in Settings → Push, the segment builder adds push filters: pushDevice counts only active devices. pushDelivered means the device reported showing the notification, which browsers do automatically and apps do when they report it. Test pushes never count. See Push notifications.

Engagement Filters

Engagement filters (emailSent, emailDelivered, emailOpened, emailClicked, emailBounced, emailComplained) accept four kinds of value:
  • A rolling time window in days or hours: 7d, 30d, 90d, 180d, all, or whole hours from 1h to 8760h such as 6h or 24h
  • A specific sent campaign: campaign:<campaign_id>
  • An email-type scope with a time window: marketing:<timeRange> or transactional:<timeRange>
  • A count with a time window: count:timeRange (only with the at_least / less_than_count operators)
Email-type scopes use the delivery policy captured at send time: marketing covers campaigns, marketing automations, and Send API calls made with emailType: "marketing"; transactional covers transactional-policy sends. This is how you avoid over-emailing without transactional traffic muddying the picture. For example, “hasn’t received a marketing email in the last week - receipts and password resets don’t count”:
Hour windows are measured to the exact hour, so 24h means the 24 hours before the segment is evaluated, not the current calendar day. Count filters are exact for hour windows up to 168h; longer hour windows count like the equivalent day window. Membership is re-checked when the segment is evaluated, so automations that react to someone entering or leaving a short window can lag by a few minutes. Use them for fast follow-ups, such as everyone who opened any email in the last 24 hours or clicked at least twice in the last 12 hours:
Combine two engagement conditions with “Match any” to save audiences like “opened any email in the last 24 hours, or opened yesterday’s newsletter” (emailOpened is 24h OR emailOpened is campaign:<campaign_id>). Ambiguous older automation and Send API events created before a send-time policy snapshot was recorded are not assigned to either scope. Unscoped engagement filters continue to include those events. Email-type values work with presence operators: is, is_not, and - for emailBounced - is_temporary_bounce or is_permanent_bounce. They cannot carry a count or be combined with a campaign:<campaign_id> value. Count values let you segment by how many times someone opened or clicked, not just whether they did. For example:
  • “Best clickers - clicked 10 or more times, ever”:
  • “Suspicious openers - opened 10+ emails but never clicked (likely bot or spamtrap opens)”:
  • “Fading subscribers - fewer than 2 opens in the last 90 days”:
Count values cannot be combined with campaign-specific values - a campaign:<campaign_id> value always checks presence, not a count. Combining two engagement filters with AND lets you target narrow audiences that rolling windows can’t express. For example:
  • “Subscribers who bounced the launch announcement but did not bounce the follow-up”:
  • “Subscribers who opened the March newsletter and then clicked the April promo”:
Campaign-specific filters are evaluated across all time, so they do not interact with the 7/30/90/180 day windows. To combine “bounced this specific campaign” with “hasn’t bounced anything in the last 30 days”, use two separate filters. In the dashboard value picker, rolling windows and sent campaigns now appear in separate sections so you can scroll straight to the campaign you want. The AI filter builder also understands natural phrasing like “bounced the welcome email but not the onboarding email” and resolves the names against your sent campaigns.

Saved Segment Logic And Counts

Saved segments can combine filters with either AND or OR logic at every group level:
  • Use AND when every filter must match
  • Use OR when any one filter should match
You can also nest groups for expressions such as last_login within 90 days AND (plan_end is empty OR plan_end is before today). In the API, nested segments use the v2 root shape with kind: "group" and children containing filter leaves or more groups. Existing flat filters plus filterJoinOperator requests still work. Array-of-object attributes use wildcard paths such as history_events[].eventvenue_id. When two or more positive filters on the same array path are connected only by AND, one shared array element must satisfy every condition. For example, a 2010 visit at one venue plus an unrelated recent booking elsewhere does not satisfy “visited this venue recently.” Negative filters (is_not, not_contains, and is_empty) combine independently because each means that no array element may match its condition. Saved segments support two additional segment-only fields:
  • event - filters by custom subscriber events. Use values like saas.purchase:30d, saas.purchase:all, or saas.purchase:5:30d with at_least / less_than_count.
  • segment - references another saved segment by ID, so you can compose one segment from another. Sequenzy protects evaluation from cycles and excessive nesting depth.
In the dashboard, Sequenzy may show two different counts for a saved segment:
  • Matched contacts - every contact that matches the segment definition, regardless of status
  • Active subscribers - matched contacts who are still eligible for campaigns
Campaigns only send to active subscribers, so campaign recipient previews use the active count rather than the broader matched-contact total.

Suggested Segments

The Segments tab on the Subscribers page suggests segments you haven’t created yet. Ready-made templates matched to your business type are always available, and Suggest with AI analyzes what is actually in your workspace - your tags, custom attributes, recently fired events, lists, and existing segments - and proposes segments built from that data. Each AI suggestion is verified against your subscribers before it is shown, so every card carries a live subscriber count and suggestions that would match nobody are dropped. Clicking a suggestion opens it prefilled in the segment editor; nothing is saved until you review and confirm it. Generated suggestions stay on the page across visits until you use them or generate new ones. Each AI suggestion also carries a recommended next step. After you save the segment, one click either opens a new campaign with its audience already set to that segment, or opens the sequence template picker with the new sequence set to trigger when contacts enter the segment.

Date Filter Examples

Rolling relative examples
Fixed date examples
Custom attribute date examples

Best Practices

1. Capture Data at Sign-up

Collect custom attributes when users first sign up:

2. Keep Attributes Updated

Sync changes from your app to Sequenzy:

3. Use Tags for Segments

Tags are more flexible than custom attributes for segmentation:

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

Background tagging

Adding tags from Contacts runs as a background task. You can leave the page and return to Background tasks to check progress, inspect failures or cancel future work. Tagging in Contacts enables tag automations; API, CLI and MCP tagging defaults to skipping automations unless you explicitly enable them. Selection reads live pages before applying tags and excludes contacts created after the request. It is not a point-in-time snapshot: changes to a contact during selection can affect membership. Once selection finishes, tagging uses those selected IDs; changing tags cannot pull additional contacts into the same task. Deleted contacts are counted as failed. Inspect processed, succeeded, failed and failures, including on completed tasks. The failure sample contains up to twenty contacts. If a worker stops while updating a contact, the task reports an uncertain outcome and does not automatically repeat that action. Check that contact before starting another tagging task. Cancellation keeps applied tags and reports an update already in flight as uncertain. Use subscribers:read to inspect tasks. Tagging also requires subscribers:tag; creating tag definitions requires tags:write, and enabling automations requires automations:trigger. Personal keys retain your current company role restrictions. Workers recheck permissions as they process pages.
Reuse the same requestKey and settings after a timeout or interrupted start response. The CLI prints its chosen recovery key before sending the request. Different settings with the same key return 409. Tasks have a seven-day processing deadline; terminal records are retained for seven days afterward. See Start a Subscriber Operation for the HTTP contract.

Capture submission answers

Open your form, popup or landing page and choose Submissions to view saved contact details and answers, filter by an exact custom field name and answer, or export matching records. Snapshots preserve the submitted answers even if a contact changes later. Tracking starts with new submissions; existing profile attributes are not backfilled as historical submissions. Deleting the contact or source removes its records. See List Form Submissions. Recovered historical records are marked Reconstructed. Their displayed date is the historical event time, and their form association is inferred. Missing answers are not filled in from current contact profiles.

Tags

Learn about tagging and segmentation

Events

Track subscriber actions with events

Sequences

Automate emails based on subscriber data

API Reference

Subscribers API documentation