Create a program

POST

programs

import { createClient } from "@norbelys/sdk";

const norbelys = createClient({ apiKey: process.env.NORBELYS_API_KEY });

const { data, error } = await norbelys.programs.create({ name: "Q3 outbound — founders" });
if (error) {
  throw new Error(error.error.message);
}
console.log(data);

{
  "activeDays": [
    1,
    2,
    3,
    4,
    5
  ],
  "addUnsubscribe": true,
  "autoPauseOnCompanyReply": true,
  "bouncePauseThreshold": 2,
  "id": "prg_b2n4x8mq1w7e9rk3v5tz0yc6",
  "jitterMaxSeconds": 60,
  "jitterMinSeconds": 30,
  "kind": "cold_sequence",
  "name": "Q3 outbound — founders",
  "newPerDay": 25,
  "pausedMeta": {
    "rate": 6.7,
    "threshold": 2
  },
  "pausedReason": "bounce_rate",
  "plainTextMode": true,
  "senderTags": [
    "acme-pool"
  ],
  "sendIntervalMinutes": 5,
  "spamPauseThreshold": 0.3,
  "status": "active",
  "stopCondition": "reply",
  "timezone": "America/Chicago",
  "timezoneSource": "sender",
  "trackClicks": true,
  "trackingDomainId": "<string>",
  "trackOpens": true,
  "unsubscribeText": "<string>",
  "variantDistribution": "pattern",
  "windowFrom": "09:00",
  "windowTo": "17:00",
  "stats": {
    "completion": 0.62,
    "leadCount": 480,
    "nextSendAt": "<unknown>"
  },
  "archivedAt": "<unknown>",
  "createdAt": "<unknown>",
  "object": "program",
  "pausedAt": "<unknown>",
  "startDate": "2026-07-01T14:00:00.000Z",
  "updatedAt": "<unknown>",
  "senders": [
    {
      "fromEmail": "[email protected]",
      "fromName": "Ada from Acme",
      "id": "snd_pfh0haxfpzowht3oi213cqos",
      "dailyLimit": 50,
      "minGapMinutes": 6,
      "nextSendAt": "<unknown>",
      "poolQueued": 9814,
      "queued": 12,
      "reputation": "good",
      "state": "healthy",
      "via": "tag"
    }
  ],
  "steps": [
    {
      "abMinSample": 100,
      "abMode": "ai_percentage",
      "abTestPct": 30,
      "abWinnerVariantId": "var_q3e7r1t9y5u2i8o4p0a6s2df",
      "abWinningMetric": "reply",
      "channel": "email",
      "id": "stp_m8k2w9qe4r7t1y5u3i0o6pl2",
      "orderIdx": 1,
      "programId": "prg_b2n4x8mq1w7e9rk3v5tz0yc6",
      "type": "email",
      "waitDays": 3,
      "variants": [
        {
          "channel": "email",
          "content": {
            "ctaOverrideReason": "<string>",
            "html": "<string>",
            "preheader": "<string>",
            "subject": "Quick question, {{ firstname | default: 'there' }}",
            "text": "<string>",
            "ai": "<unknown>"
          },
          "id": "var_q3e7r1t9y5u2i8o4p0a6s2df",
          "label": "A",
          "stepId": "stp_m8k2w9qe4r7t1y5u3i0o6pl2",
          "weight": 1,
          "archivedAt": "<unknown>",
          "createdAt": "<unknown>",
          "object": "variant"
        }
      ],
      "archivedAt": "<unknown>",
      "createdAt": "<unknown>",
      "object": "step"
    }
  ]
}

{
  "error": {
    "code": "invalid_param",
    "message": "<string>",
    "type": "invalid_request",
    "doc_url": "<string>",
    "hint": "<string>"
  }
}

{
  "error": {
    "code": "invalid_param",
    "message": "<string>",
    "type": "invalid_request",
    "doc_url": "<string>",
    "hint": "<string>"
  }
}

{
  "error": {
    "code": "invalid_param",
    "message": "<string>",
    "type": "invalid_request",
    "doc_url": "<string>",
    "hint": "<string>"
  }
}

{
  "error": {
    "code": "invalid_param",
    "message": "<string>",
    "type": "invalid_request",
    "doc_url": "<string>",
    "hint": "<string>"
  }
}

{
  "error": {
    "code": "invalid_param",
    "message": "<string>",
    "type": "invalid_request",
    "doc_url": "<string>",
    "hint": "<string>"
  }
}

{
  "error": {
    "code": "invalid_param",
    "message": "<string>",
    "type": "invalid_request",
    "doc_url": "<string>",
    "hint": "<string>"
  }
}

{
  "error": {
    "code": "invalid_param",
    "message": "<string>",
    "type": "invalid_request",
    "doc_url": "<string>",
    "hint": "<string>"
  }
}

{
  "error": {
    "code": "invalid_param",
    "message": "<string>",
    "type": "invalid_request",
    "doc_url": "<string>",
    "hint": "<string>"
  }
}

Authorizations

Authorization

string

header

required

Org-scoped Norbelys API key. Create one in Settings → API keys and send it as Authorization: Bearer ak_….

Headers

Idempotency-Key

string

Opt-in idempotency for a safely retried write: reuse the same key to replay the original result for 24h instead of re-executing. Recommended on every POST.

Maximum string length: 255

Body

application/json

name

string

required

Display name.

Minimum string length: 1

Example:

"Q3 outbound — founders"

activeDays

integer[] | null

Weekdays sends are allowed (0=Sun..6=Sat).

Required range: 0 <= x <= 6

addUnsubscribe

boolean

Attach RFC 8058 one-click unsubscribe headers + footer. Defaults off (opt-in).

autoPauseOnCompanyReply

boolean

Pause every lead at a company once one of them replies.

bouncePauseThreshold

number

Auto-pause when the bounce rate reaches this percent; 0 disables. Default 2.

Required range: 0 <= x <= 100

Example:

2

jitterMaxSeconds

integer

Random extra wait per send, upper bound (seconds).

Required range: x >= 0

Example:

60

jitterMinSeconds

integer

Random extra wait per send, lower bound (seconds).

Required range: x >= 0

Example:

30

kind

enum<string>

Defaults to "cold_sequence".

Available options:

cold_sequence

newPerDay

integer

New leads started per day for the whole campaign, shared across all its mailboxes (follow-ups excluded); 0 = uncapped.

Required range: x >= 0

Example:

25

plainTextMode

boolean

Send the body as plain text only: no HTML part, open pixel, or link tracking.

senderTags

string[] | null

Dynamic mailbox selector: senders carrying ANY of these tags are auto-attached (and auto-detached as tags change). Manual attaches are unaffected. null clears the selector (tag-derived mailboxes detach).

Maximum array length: 20

Required string length: 1 - 50

Example:

["acme-pool"]

sendIntervalMinutes

integer

Minutes between sends from one mailbox (cold-email floor is 3).

Required range: x >= 3

Example:

5

spamPauseThreshold

number

Auto-pause when the spam-complaint rate reaches this percent; 0 disables. Default 0.3.

Required range: 0 <= x <= 100

Example:

0.3

startDate

integer | null

Scheduled first-send instant, epoch ms.

Required range: x >= 0

Example:

1767283200000

steps

ProgramStepInput · object[]

Build the whole cadence in one call: ordered steps, each with its arms. Omit to start empty and add steps later via programs.update.

Show child attributes

stopCondition

enum<string>

Engagement that pulls a lead out of the cadence: reply, click, open, none.

Available options:

reply,

click,

open,

none

timezone

string

IANA timezone.

Example:

"America/Chicago"

timezoneSource

enum<string>

Evaluate the send window in the campaign timezone (sender, default) or each person's timezone (recipient).

Available options:

sender,

recipient

Example:

"recipient"

trackClicks

boolean

Rewrite links to track clicks.

trackingDomainId

string | null

Optional campaign-level tracking hostname override; null resolves automatically per sender domain.

trackOpens

boolean

Insert the open pixel.

unsubscribeText

string

Custom unsubscribe footer copy.

variantDistribution

enum<string>

How A/B arms are spread across leads with no decided winner: pattern (deterministic per-lead hash) or random (independent roll per lead).

Available options:

pattern,

random

windowFrom

string | null

Daily window start, "HH:MM".

Pattern: ^([01]?\d|2[0-3]):[0-5]\d$

Example:

"09:00"

windowTo

string | null

Daily window end, "HH:MM".

Pattern: ^([01]?\d|2[0-3]):[0-5]\d$

Example:

"17:00"

Response

activeDays

integer[] | null

required

Weekdays sends are allowed (0=Sun..6=Sat).

Required range: 0 <= x <= 6

Example:

[1, 2, 3, 4, 5]

addUnsubscribe

boolean

required

Attach RFC 8058 one-click unsubscribe headers + footer.

autoPauseOnCompanyReply

boolean

required

Pause every lead at a company once one of them replies.

bouncePauseThreshold

number

required

Auto-pause when the bounce rate reaches this percent; 0 disables.

Required range: 0 <= x <= 100

Example:

2

string

required

The program id.

Example:

"prg_b2n4x8mq1w7e9rk3v5tz0yc6"

jitterMaxSeconds

integer

required

Random extra wait per send, upper bound (seconds).

Required range: x >= 0

Example:

60

jitterMinSeconds

integer

required

Random extra wait per send, lower bound (seconds).

Required range: x >= 0

Example:

30

kind

enum<string>

required

Kind of sending; cold_sequence is the only kind today.

Available options:

cold_sequence

Example:

"cold_sequence"

name

string

required

Display name.

Example:

"Q3 outbound — founders"

newPerDay

integer

required

New leads started per day for the WHOLE campaign, shared across all its mailboxes (follow-ups are not counted). 0 = no daily cap — new leads flow at mailbox capacity. Real throughput is always bounded by the mailboxes' own daily limits.

Required range: x >= 0

Example:

25

pausedMeta

ProgramPauseMeta · object | null

required

For an auto-pause, the numbers behind it (measured rate vs threshold); null for a manual pause or no pause.

Show child attributes

pausedReason

enum<string> | null

required

Why it's paused, or null: manual (an operator paused it), bounce_rate or spam_rate (an auto circuit-breaker tripped), orphaned_sender (it lost its last live mailbox).

Available options:

manual,

bounce_rate,

spam_rate,

orphaned_sender

Example:

"bounce_rate"

plainTextMode

boolean

required

Send the body as plain text only: no HTML part, open pixel, or link tracking.

senderTags

string[] | null

required

Dynamic mailbox selector: senders carrying ANY of these tags are auto-attached to (and auto-detached from) the campaign as their tags change. Manual attaches are unaffected. null = manual assignment only.

Example:

["acme-pool"]

sendIntervalMinutes

integer

required

Minutes between sends from one mailbox.

Required range: x >= 0

Example:

5

spamPauseThreshold

number

required

Auto-pause when the spam-complaint rate reaches this percent; 0 disables.

Required range: 0 <= x <= 100

Example:

0.3

status

enum<string>

required

Lifecycle status: draft, active, paused, done.

Available options:

draft,

active,

paused,

done

Example:

"active"

stopCondition

enum<string>

required

Engagement that pulls a lead out of the cadence: reply, click, open, none.

Available options:

reply,

click,

open,

none

Example:

"reply"

timezone

string

required

IANA timezone the window applies in.

Example:

"America/Chicago"

timezoneSource

enum<string>

required

Evaluate the sending window in the campaign timezone (sender) or each person's timezone (recipient, falling back to the campaign timezone when absent).

Available options:

sender,

recipient

Example:

"sender"

trackClicks

boolean

required

Rewrite links to track clicks.

trackingDomainId

string | null

required

Optional campaign-level tracking hostname override; null resolves automatically per sender domain.

trackOpens

boolean

required

Insert the open pixel.

unsubscribeText

string | null

required

Custom unsubscribe footer copy.

variantDistribution

enum<string>

required

How A/B arms are spread across leads with no decided winner: pattern (deterministic per-lead hash) or random (independent roll per lead).

Available options:

pattern,

random

Example:

"pattern"

windowFrom

string | null

required

Daily window start, "HH:MM".

Example:

"09:00"

windowTo

string | null

required

Daily window end, "HH:MM".

Example:

"17:00"

stats

ProgramStats · object

required

Per-campaign state rollup: enrollment counts + next-send schedule.

Show child attributes

archivedAt

any

When it was archived, or null if live.

createdAt

any

Creation instant (RFC 3339).

object

any

default:program

Always "program" — the resource discriminator.

pausedAt

any

When it was paused (RFC 3339), or null.

startDate

any

Scheduled first-send instant (RFC 3339), or null.

Example:

"2026-07-01T14:00:00.000Z"

updatedAt

any

Last-update instant (RFC 3339).

senders

ProgramSenderRef · object[]

The attached mailboxes — present when expand[]=senders.

Show child attributes

steps

StepWithVariants · object[]

The cadence with arms — present when expand[]=steps (always returned by create/update).

Show child attributes

import { createClient } from "@norbelys/sdk";

const norbelys = createClient({ apiKey: process.env.NORBELYS_API_KEY });

const { data, error } = await norbelys.programs.create({ name: "Q3 outbound — founders" });
if (error) {
  throw new Error(error.error.message);
}
console.log(data);

{
  "activeDays": [
    1,
    2,
    3,
    4,
    5
  ],
  "addUnsubscribe": true,
  "autoPauseOnCompanyReply": true,
  "bouncePauseThreshold": 2,
  "id": "prg_b2n4x8mq1w7e9rk3v5tz0yc6",
  "jitterMaxSeconds": 60,
  "jitterMinSeconds": 30,
  "kind": "cold_sequence",
  "name": "Q3 outbound — founders",
  "newPerDay": 25,
  "pausedMeta": {
    "rate": 6.7,
    "threshold": 2
  },
  "pausedReason": "bounce_rate",
  "plainTextMode": true,
  "senderTags": [
    "acme-pool"
  ],
  "sendIntervalMinutes": 5,
  "spamPauseThreshold": 0.3,
  "status": "active",
  "stopCondition": "reply",
  "timezone": "America/Chicago",
  "timezoneSource": "sender",
  "trackClicks": true,
  "trackingDomainId": "<string>",
  "trackOpens": true,
  "unsubscribeText": "<string>",
  "variantDistribution": "pattern",
  "windowFrom": "09:00",
  "windowTo": "17:00",
  "stats": {
    "completion": 0.62,
    "leadCount": 480,
    "nextSendAt": "<unknown>"
  },
  "archivedAt": "<unknown>",
  "createdAt": "<unknown>",
  "object": "program",
  "pausedAt": "<unknown>",
  "startDate": "2026-07-01T14:00:00.000Z",
  "updatedAt": "<unknown>",
  "senders": [
    {
      "fromEmail": "[email protected]",
      "fromName": "Ada from Acme",
      "id": "snd_pfh0haxfpzowht3oi213cqos",
      "dailyLimit": 50,
      "minGapMinutes": 6,
      "nextSendAt": "<unknown>",
      "poolQueued": 9814,
      "queued": 12,
      "reputation": "good",
      "state": "healthy",
      "via": "tag"
    }
  ],
  "steps": [
    {
      "abMinSample": 100,
      "abMode": "ai_percentage",
      "abTestPct": 30,
      "abWinnerVariantId": "var_q3e7r1t9y5u2i8o4p0a6s2df",
      "abWinningMetric": "reply",
      "channel": "email",
      "id": "stp_m8k2w9qe4r7t1y5u3i0o6pl2",
      "orderIdx": 1,
      "programId": "prg_b2n4x8mq1w7e9rk3v5tz0yc6",
      "type": "email",
      "waitDays": 3,
      "variants": [
        {
          "channel": "email",
          "content": {
            "ctaOverrideReason": "<string>",
            "html": "<string>",
            "preheader": "<string>",
            "subject": "Quick question, {{ firstname | default: 'there' }}",
            "text": "<string>",
            "ai": "<unknown>"
          },
          "id": "var_q3e7r1t9y5u2i8o4p0a6s2df",
          "label": "A",
          "stepId": "stp_m8k2w9qe4r7t1y5u3i0o6pl2",
          "weight": 1,
          "archivedAt": "<unknown>",
          "createdAt": "<unknown>",
          "object": "variant"
        }
      ],
      "archivedAt": "<unknown>",
      "createdAt": "<unknown>",
      "object": "step"
    }
  ]
}

{
  "error": {
    "code": "invalid_param",
    "message": "<string>",
    "type": "invalid_request",
    "doc_url": "<string>",
    "hint": "<string>"
  }
}

{
  "error": {
    "code": "invalid_param",
    "message": "<string>",
    "type": "invalid_request",
    "doc_url": "<string>",
    "hint": "<string>"
  }
}

{
  "error": {
    "code": "invalid_param",
    "message": "<string>",
    "type": "invalid_request",
    "doc_url": "<string>",
    "hint": "<string>"
  }
}

{
  "error": {
    "code": "invalid_param",
    "message": "<string>",
    "type": "invalid_request",
    "doc_url": "<string>",
    "hint": "<string>"
  }
}

{
  "error": {
    "code": "invalid_param",
    "message": "<string>",
    "type": "invalid_request",
    "doc_url": "<string>",
    "hint": "<string>"
  }
}

{
  "error": {
    "code": "invalid_param",
    "message": "<string>",
    "type": "invalid_request",
    "doc_url": "<string>",
    "hint": "<string>"
  }
}

{
  "error": {
    "code": "invalid_param",
    "message": "<string>",
    "type": "invalid_request",
    "doc_url": "<string>",
    "hint": "<string>"
  }
}

{
  "error": {
    "code": "invalid_param",
    "message": "<string>",
    "type": "invalid_request",
    "doc_url": "<string>",
    "hint": "<string>"
  }
}

Analytics

Domains

Fields

Files

Groups

Integrations

Messages

Organization

People

Programs

Segments

Senders

Suppressions

Verify

Authorizations

Headers

Body

Response