Campaigns & Segments

Overview

The campaigns system lets you reach the right customers at the right time. Define segments using rule-based filters on customer data — order history, location, tags, spend — then launch campaigns across any channel. Dynamic segments update automatically as customers match or unmatch your criteria. Automation rules let you trigger campaigns based on real-time events like completed orders or abandoned carts.

Create a Segment

Segments define your target audience using composable rules. Each rule specifies a customer field, an operator, and a value. Dynamic segments re-evaluate membership automatically; static segments are fixed at creation time.

const whale = new WhaleClient("wk_live_...");

const segment = await whale.segments.create({
  name: "Repeat Buyers",
  rules: [
    { field: "total_orders", operator: "gte", value: 5 },
    { field: "last_order_at", operator: "gte", value: "2026-01-01T00:00:00Z" }
  ],
  is_dynamic: true,
  metadata: {
    description: "Customers with 5+ orders since Jan 2026"
  }
});

// Response
{
  "object": "segment",
  "id": "seg_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "Repeat Buyers",
  "rules": [
    { "field": "total_orders", "operator": "gte", "value": 5 },
    { "field": "last_order_at", "operator": "gte", "value": "2026-01-01T00:00:00Z" }
  ],
  "is_dynamic": true,
  "customer_count": 342,
  "created_at": "2026-03-10T10:00:00.000Z"
}

Create a Campaign

Campaigns combine a segment, a channel, and a template. Specify scheduled_at to queue the campaign for future delivery, or omit it to save as a draft. Supported types include email, sms, push, and direct_mail.

const campaign = await whale.campaigns.create({
  name: "Spring Sale — Repeat Buyers",
  type: "email",
  segment_id: "seg_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  template_id: "tmpl_f6a7b8c9-d0e1-2345-fghi-jk6789012345",
  scheduled_at: "2026-03-15T09:00:00Z",
  metadata: {
    utm_source: "email",
    utm_campaign: "spring-sale-2026"
  }
});

// Response
{
  "object": "campaign",
  "id": "cmp_d4e5f6a7-b8c9-0123-defg-hi4567890123",
  "name": "Spring Sale — Repeat Buyers",
  "type": "email",
  "status": "scheduled",
  "segment_id": "seg_a1b2c3d4...",
  "template_id": "tmpl_f6a7b8c9...",
  "recipient_count": 342,
  "scheduled_at": "2026-03-15T09:00:00Z",
  "created_at": "2026-03-10T10:30:00.000Z"
}

Campaign Analytics

Once a campaign is active or completed, query its performance metrics. Analytics include delivery rates, engagement (opens and clicks), conversions, and attributed revenue. Metrics update in near real-time during delivery.

const analytics = await whale.campaigns.analytics("cmp_d4e5f6a7...");

// Response
{
  "object": "campaign_analytics",
  "campaign_id": "cmp_d4e5f6a7...",
  "status": "completed",
  "sent": 342,
  "delivered": 338,
  "opened": 187,
  "clicked": 94,
  "conversions": 31,
  "revenue": 4729.50,
  "open_rate": 0.553,
  "click_rate": 0.278,
  "conversion_rate": 0.092,
  "unsubscribed": 2,
  "bounced": 4,
  "completed_at": "2026-03-15T14:22:00.000Z"
}

Automation Rules

Automation rules trigger campaigns or actions based on real-time events. Define a trigger event, optional conditions to filter which events qualify, and one or more actions to execute. Rules run continuously and can be paused or resumed.

const rule = await whale.automationRules.create({
  name: "Post-Purchase Thank You",
  trigger_event: "order.completed",
  conditions: [
    { field: "order.total", operator: "gte", value: 100 }
  ],
  actions: [
    {
      type: "send_email",
      template_id: "tmpl_thankyou_vip",
      delay: "1h"
    }
  ],
  is_active: true
});

// Response
{
  "object": "automation_rule",
  "id": "rule_e5f6a7b8-c9d0-1234-efgh-ij5678901234",
  "name": "Post-Purchase Thank You",
  "trigger_event": "order.completed",
  "conditions": [
    { "field": "order.total", "operator": "gte", "value": 100 }
  ],
  "actions": [
    {
      "type": "send_email",
      "template_id": "tmpl_thankyou_vip",
      "delay": "1h"
    }
  ],
  "is_active": true,
  "times_triggered": 0,
  "created_at": "2026-03-10T11:00:00.000Z"
}

API Reference