Audience

Segments

Live, rule-based groups of contacts that recalculate as your audience changes — target them from campaigns and reference them by id in the API.

A segment is a saved set of rules over your contacts. Instead of exporting a static list, you describe who belongs — subscribed contacts who fired order.completed in the last 30 days, say — and Deckle keeps the membership up to date for you.

What is a segment#

A segment is a live, rule-based group of contacts. You define the rules once; Deckle evaluates them continuously against your audience. A contact is a member whenever they match the rules and drops out the moment they stop matching — you never maintain the list by hand.

Segments are the marketing counterpart to your event-driven core: contacts are keyed by email, events record what they do, and a segment turns those attributes and events into a targetable audience for a campaign.

Managed in the dashboard

Segments are created and edited in the dashboard under Audience → Segments. There is no public write endpoint — you can’t create or update a segment over the API. You reference an existing segment by its id where a campaign accepts a segment.

Rules#

A segment is built from rules, combined into AND / OR groups. Within a group you choose whether a contact must match every rule (AND) or any rule (OR), and you can nest groups to express more precise audiences. Each rule targets one of four categories.

Rule type	Matches on	Example
`attribute`	A contact field or custom key in the contact’s stored data	`data.plan` is `pro`
`event`	Whether a named event was recorded for the contact	fired `order.completed` at least once
`engagement`	Send activity — opens and clicks on your email	opened an email in the last 30 days
`subscribed`	The contact’s subscription state	`subscribed` is `true`

A typical segment mixes categories. To reach engaged pro customers, you might combine a subscribed rule, an attribute rule, and an engagement rule inside a single AND group.

segment-rules.json

{
  "match": "and",
  "rules": [
    { "type": "subscribed", "value": true },
    { "type": "attribute", "field": "data.plan", "op": "eq", "value": "pro" },
    {
      "match": "or",
      "rules": [
        { "type": "event", "name": "order.completed", "op": "occurred" },
        { "type": "engagement", "metric": "opened", "within_days": 30 }
      ]
    }
  ]
}

Preview before you send

The segment editor shows an estimated member count and a sample of matching contacts as you add rules, so you can sanity-check the audience before you target it from a campaign.

Live membership#

Segment membership is not a snapshot. Deckle recalculates it as your data changes: when a contact is created or updated, when an event is recorded, and when engagement (an open or click) comes in. A contact enters or leaves the segment automatically based on whether they currently match the rules.

How a contact moves in and out#

Because membership follows your data, ordinary API calls change who belongs — no separate segment call is needed.

What triggers a recalculation

contact changeattribute rulesOptional

Upserting a contact with POST /v1/contacts or updating custom data re-evaluates attribute and subscribed rules for that contact.

event recordedevent rulesOptional

Posting an event with POST /v1/events can pull a contact into a segment whose rules require that event.

engagementengagement rulesOptional

Opens and clicks reported back from your sends keep engagement-based rules current.

For example, recording order.completed for a subscribed pro customer adds them to the segment above on the next evaluation — you only had to send the event.

import { Deckle } from "@deckle/sdk";

const deckle = new Deckle(process.env.DECKLE_API_KEY!);

// Recording this event may move the contact into a segment
// whose rules include order.completed.
await deckle.events.create({
  name: "order.completed",
  email: "jane@example.com",
  data: { order_id: "order_1234", amount: 4900 },
});

Use in campaigns#

The main job of a segment is to target a campaign. When you create a campaign you set its target to segment and pass the segment’s id in the segment field. Membership is resolved when the campaign sends, so you reach whoever matches the rules at send time.

Build the segment in the dashboard

Open Audience → Segments, add your AND/OR rules, and save. Copy the segment’s id (it looks like seg_...) from the segment detail page.

Target it from a campaign

Create a draft campaign with target: "segment" and segment: "seg_...". The campaign will broadcast only to contacts in that segment.

Send with a live key

Send the campaign with POST /v1/campaigns/{id}/send using a sk_live_ key. Deckle resolves current membership and delivers to it.

import { Deckle } from "@deckle/sdk";

const deckle = new Deckle(process.env.DECKLE_API_KEY!);

// Reference the segment by id — there is no segment write API.
const campaign = await deckle.campaigns.create({
  name: "Pro customer update",
  subject: "What's new for Pro",
  from_name: "Acme",
  from_email: "hello@acme.com",
  target: "segment",
  segment: "seg_engaged_pro",
});

await deckle.campaigns.send(campaign.id); // live key only

Reference by id only

The API reads segments but never writes them. Wherever a campaign accepts a segment, pass the id of a segment you built in the dashboard — you can’t define rules inline.

Next steps#

Campaigns

Broadcast to a segment or your whole list, with A/B subject lines and reports.

Contacts

Create and update the contacts and custom data your segment rules match on.