Skip to main content
POST
Create Sequence
If you use an account key as a marketer, choose an existing sender and Reply-To profile. A request that needs a new profile returns 400 before creating profiles, labels, or campaign/sequence changes. This also applies to email steps and inserted sequence branches. An owner or admin can add the identity first; a step-level display-name override can still use an existing profile.
Create an automation sequence that sends emails based on triggers. You can:
  • Provide a goal to have AI generate the email content
  • Provide steps with explicit email content and actions such as discount creation or Update Subscriber
  • Omit both goal and steps to create the same blank trigger-to-completion draft the dashboard starts with
New sequences are created as drafts, so the response reports "effectiveStatus": "draft" and nobody is enrolled until you call Enable Sequence. See List Sequences for the full run-state mapping.

​
Request

​
string
required
Name for the sequence
​
string
Dashboard description for the sequence. For a seasonal sale sequence (for example a Black Friday countdown) it doubles as the offer: generated emails quote its offer sentences (discount, code, scope) verbatim, so keep internal notes out of it.
​
string[]
Dashboard label names. Missing labels are created automatically.
​
boolean
Whether recipients can cancel this sequence from email preferences.
​
boolean
default:"false"
Only enroll contacts whose status is active. When false, unsubscribed and bounced contacts still enter on tag, event, list and contact triggers, so non-marketing steps such as tags, webhooks and transactional emails run for them, and their marketing emails are skipped at send time. Set true to keep them out of the sequence entirely. Contacts waiting to confirm double opt-in still wait at the trigger and continue once they confirm.
​
string[]
Up to 10 addresses blind-copied on every sequence email.
​
string
Trigger type: contact_added, tag_added, segment_entered, segment_exited, event_received, inbound_webhook, inactivity, frequency, or manual. segment_exited enrolls active contacts who stop matching the segment; unsubscribing or bouncing does not count as leaving. Defaults to contact_added when omitted. manual never enrolls anyone automatically: pair it with keyDates and waitUntilKeyDate steps for a one-time countdown, then enroll the audience after enabling the sequence.
​
string
From address for every email in this sequence. Its domain must be configured and verified. Mutually exclusive with senderProfileId.
​
string
Display name recipients see, e.g. Brennon at TradeTally. Selects the sender identity of that name on fromEmail, creating it when the address has no identity by that name; the mailbox’s other display names, and everything pinned to them, are untouched. Requires fromEmail; omit it when you send senderProfileId, which already carries its own display name.
​
string
Existing sender profile ID. It already supplies both the From address and the display name, so send it on its own and omit fromEmail and fromName. To keep this profile under a different display name, set fromName on the email steps instead, where it is a per-step override.
​
string
Reply-To address for every email in this sequence. Mutually exclusive with replyProfileId.
​
string
Display name for the Reply-To address. Requires replyTo; omit it when you send replyProfileId, which already carries its own display name. An address carries one Reply-To name company-wide: if replyTo already has a saved profile under a different name, that saved name is kept and the response warnings array says so.
​
string
Existing reply profile ID. It already supplies both the Reply-To address and the display name, so send it on its own and omit replyTo and replyToName.
​
string
List ID (for contact_added trigger). Omit it to use listScope instead. Use listIds to trigger on several lists.
​
string[]
Several list IDs (for contact_added trigger). A contact joining any of them enters the sequence. Takes precedence over listId when you send both. Cannot be combined with listScope. Up to 25 lists.
​
string
default:"any_contact"
For contact_added triggers with no list at all. any_contact enrolls every contact that is added, including contacts that join no list - which is what an integration creates when its list targeting is empty. any_list waits until the contact joins a list. Cannot be combined with listId or listIds.
​
string
Tag name (for tag_added trigger). Use tagNames to trigger on several tags.
​
string[]
Several tag names (for tag_added trigger). Receiving any of them enters the contact into the sequence. Takes precedence over tagName when you send both. Up to 25 tags.
​
string
Segment ID (for segment_entered and segment_exited triggers)
​
boolean
For segment_entered, cancel an enrollment when the subscriber leaves the segment.
​
string
Event name (for event_received, inactivity, frequency triggers)
​
string
Integration slug for an inbound_webhook trigger.
​
string
Integration event key for an inbound_webhook trigger.
​
object
Custom integration metadata for an inbound_webhook trigger.
​
array
Event property filters (for event_received and inbound_webhook triggers, maximum 10). The sequence only starts when the triggering event’s properties match ALL filters. Use a dot-path into the event properties; use [] to match items inside arrays, for example lineItems[].providerProductId.
​
number
Days of inactivity (for inactivity trigger)
​
string
For inactivity triggers, when to start counting for subscribers who have never performed the event: sequence_created_at or subscriber_created_at. Defaults to sequence_created_at.
​
number
Minimum event count (for frequency trigger)
​
number
Time window in days (for frequency trigger)
​
string
Re-entry mode: unlimited, one_time, or matching_field. Defaults to matching_field for Shopify replenishment and back-in-stock events, otherwise unlimited. matching_field is only valid for event_received and inbound_webhook sequence triggers.
​
string
Scalar dot-path event property used by matching_field, such as order.id or product.providerVariantId. Array traversal with [] is not supported; use propertyFilters when the trigger must match values inside an array. Leave empty for the built-in Shopify product/variant default.
​
object
Optional local-time sending window for every email step in the sequence. Email steps that become due outside the window wait until the next allowed local time.
​
boolean
default:"false"
Whether the sequence respects the company frequency cap. When true, an email step is skipped for a contact who already received the cap’s number of campaign or marketing sequence emails in its window, and the contact moves on to the next step. Transactional steps are never skipped and transactional emails never count. Has no effect until a cap is set. Non-boolean values return 422.
​
object | null
Named absolute moments the sequence counts down to, such as “Black Friday starts”. Delay steps with waitUntilKeyDate wait relative to one of them, so the whole countdown is re-timed by editing these dates. Set to null to clear.
​
object
Optional auto-stop condition, re-evaluated before every step including the first one. Use has_tag to end the sequence when a subscriber gets a tag, event_received when an event is tracked, added_to_list when a subscriber joins a list, entered_segment when a subscriber enters a segment, field_changed when a subscriber attribute changes, or none to clear auto-stop behavior. does_not_have_tag and removed_from_list stop the run whenever the subscriber lacks that tag or list membership, so they act as a required-tag or required-list allowlist and cancel everyone else before any step sends. Guarded-out contacts still enroll and are then cancelled at the trigger node, so they appear as cancellations there rather than in the active or waiting enrollment counts. Clearing the guard does not retry them: they only receive the sequence if the trigger fires for them again, and on the one_time enrollment mode not even then. event_received only counts events received after enrollment; the enrolling event and earlier history do not satisfy the stop. Use matchConfig.mode: "event_property_filter" with propertyFilters to require every literal-value filter to match a later stop event, or matchConfig.mode: "event_property" with field mapping rules to compare the stop event with the enrolling event. field_changed can include matchConfig.mode: "field_value" with an operator and comparison value. Tag and list defaults are returned with value: null and matchConfig.mode: "entry_audience"; sending that shape back preserves the per-enrollment tag or list guard.

​
Option A: AI Generation

​
string
Description of what the sequence should accomplish. AI will generate email content based on this.
​
number
Number of emails to generate (default: 5, maximum: 10)
​
number
Total duration in days used to space AI-generated emails. Omit this to use the default sequence delay schedule.
​
string
Style for the AI-generated emails: visual (designed, with heroes, imagery, and rich sections) or plain (personal, text-first notes with a single button). Defaults to the company’s saved preference when omitted.

​
Option B: Explicit Content

​
array
Array of explicit steps. Email steps must have either blocks or html; SMS steps use type: "sms" with text; push steps use type: "push" with title and/or body; in-app steps use type: "in_app" with title and/or body; discount steps use type: "create_discount"; Update Subscriber steps use type: "update_subscriber", nodeType: "action_update_attributes", and config.

​
Option C: Blank Draft

Send only name (and optionally metadata or a trigger). The API creates a disabled draft containing the trigger and completion nodes, ready for later insertSteps, branch insertion, or graph edits.

​
Request Shape and Warnings

Every trigger setting is a top-level field. A contact_added sequence for one list uses "trigger": "contact_added" and "listId", not a nested triggerConfig object. Step delays are objects such as "delay": { "days": 2 }, or delayMs. This minimal request creates a six-email draft for one list, sending the first email right away and each later email two days after the previous one:
Omit stopCondition to keep the default list guard, which stops a run when the contact leaves the list. Send { "type": "none" } to turn it off. For compatibility, some requests that do not match this shape still create the draft. The response then includes a warnings array that names each problem: Fix every warning before you enable the sequence. Send "listScope": "any_contact" when you do want every new contact. Enable Sequence still notes that audience in its warnings, so you can confirm it before contacts start entering. A field with the wrong type or an unsupported value, such as "enrollmentMode": "once" or a stopCondition sent as a string, returns 422. The response names the field in property and explains it in summary, with allowedValues for fields that accept a fixed set of values.

​
Discount Merge Tags

When a create_discount step runs, Sequenzy creates a fresh provider discount/code for that subscriber’s automation run. Later emails in the same sequence can use discount merge tags from the most recent created discount:
  • {{discount.code}}
  • {{discount.percentOff}}
  • {{discount.amountOff}}
  • {{discount.currency}}
  • {{discount.expiresAt}}
Discount sequences require a connected integration for the selected provider, such as Stripe or Shopify, before activation.

​
Enrollment Modes

Use matching_field for event-triggered sequences where each run belongs to a specific object in the event payload. It lets a subscriber have separate active runs for different products, variants, orders, subscriptions, or other event-scoped objects, while blocking duplicate active runs for the same resolved field. Set enrollmentFieldPath for custom events, or send sequenceEnrollmentKey, enrollmentKey, or common product/variant fields in the event properties.

​
Sending Windows

Use sendingWindow when a triggered sequence should start immediately but emails should only go out during allowed local hours. The window is checked before every email action, including later steps after delays or branches.

​
Event-Personalized Sequence Emails

If you create a sequence with trigger: "event_received", the event payload that enrolls the subscriber is available inside sequence emails through event. merge tags. For example, if your app sends:
You can use values like:
  • {{event.city}}
  • {{event.alert.maxSpeed}}
  • {{event.duration.hours|a few}}
Sequenzy stores the event snapshot on the sequence run, so delayed follow-up emails in the same sequence keep using the original values.

​
Examples

​
AI-Generated Content

​
Explicit Content with Blocks

​
Explicit Content with HTML (Auto-converted)

Use this when migrating from other platforms or when you have existing HTML templates (React Email, MJML, etc.).

​
Explicit Discount Action

Use this when you want Sequenzy to generate a dynamic provider discount code before sending a follow-up email. Connect the selected provider in Settings before enabling the sequence.

​
Inactivity Sequence

​
Product-Scoped Purchase Sequence (Property Filters)

Use propertyFilters to start a purchase sequence only for one specific product, for example to deliver a digital product file. Use lineItems[].providerProductId for ecommerce.order_placed events, or productIds for Stripe saas.purchase events.

​
Event-Triggered Sequence With {{event.*}}

​
Responses

​
Notes

  • The sequence is created in draft status. Use POST /api/v1/sequences/{id}/enable to activate it.
  • For backwards compatibility, POST /v1/sequences is still accepted as an alias.
  • When using email steps, each email step creates an email template in your account that can be edited later.
  • Sequences with create_discount steps require a connected integration for the selected provider before activation.
  • SMS steps require the SMS add-on (paid plans). Check Get SMS Settings first; steps added while SMS is not ready are stored but skip at runtime.
  • Push steps send only once web push, APNs or Firebase is set up. Check Get Push Settings first; see Push notifications.
  • In-app steps store each item in the contact’s in-app feed; your app must fetch and render it. See In-app messages.
  • When using goal, AI generates content asynchronously. Poll GET /api/v1/sequences/{id} to check enrichment status.
  • The first step typically has no delay (sends immediately after trigger).
  • If sendingWindow is set, each email step sends only during the allowed local hours and waits until the next allowed time otherwise.
  • For event_received sequences, properties sent to POST /api/v1/subscribers/events are available as {{event.*}} merge tags in sequence emails.
  • For custom event triggers, use the returned eventTrackingCode and eventTracking contract to implement the application-owned event feed. The contract includes normalized propertyFilters and reports whether its generated example already satisfies them through examplePayloadMatchesFilters. If that value is false, adapt the example using payloadContract and examplePayloadNote before sending it. With matching_field enrollment, every required property path must be present in properties or the sequence cannot identify the matching run.
  • When using html in steps, the content is preserved as one raw HTML block. Use blocks when you want native Sequenzy block editing.