Enroll people into a program

POST

programs

{id}

enroll

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

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

const { data, error } = await norbelys.programs.enroll("prg_y3rgwmhkbgxx", { all: null, groupIds: ["…"], importIds: ["…"], mode: "snapshot" });
if (error) {
  throw new Error(error.error.message);
}
console.log(data);

{
  "active": true,
  "alreadyEnrolled": 13,
  "enrolled": 412,
  "programId": "prg_b2n4x8mq1w7e9rk3v5tz0yc6",
  "senderIds": [
    "snd_pfh0haxfpzowht3oi213cqos"
  ],
  "suppressed": 4
}

{
  "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

Path Parameters

string

required

The program id.

Body

application/json

all

any

Enroll EVERY active person. Required explicitly — omitting all selectors is an error, never an implicit enroll-everyone.

groupIds

string[]

Enroll every LIVE person in these groups (static lists) — several at once, resolved as one union.

importIds

string[]

When the personIds came from CSV imports, the import ids — each is recorded as an audience source so the campaign shows where its people came from.

mode

enum<string>

snapshot (default): enroll the CURRENT matches once and freeze. reactive: also keep the campaign in sync with EVERY given segment — new people are enrolled automatically as they come to match. Groups are static lists, so they always behave as snapshots.

Available options:

snapshot,

reactive

personIds

string[]

Explicit person ids (CSV/preview-resolved sets).

segmentIds

string[]

Enroll every person CURRENTLY matching these segments (saved filters) — several at once, resolved as one union.

Response

active

boolean

required

Whether the program is live after this enroll (true = the new leads start sending).

alreadyEnrolled

integer

required

How many of the resolved audience were already in this program and were skipped.

Required range: x >= 0

Example:

13

enrolled

integer

required

Number of people newly enrolled.

Required range: x >= 0

Example:

412

programId

string

required

The program id.

Example:

"prg_b2n4x8mq1w7e9rk3v5tz0yc6"

senderIds

string[]

required

The program's attached mailboxes.

Example:

["snd_pfh0haxfpzowht3oi213cqos"]

suppressed

integer

required

How many of the resolved audience were excluded by the suppression list (unsubscribed, hard-bounced, or verified-undeliverable addresses never enter a campaign).

Required range: x >= 0

Example:

4

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

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

const { data, error } = await norbelys.programs.enroll("prg_y3rgwmhkbgxx", { all: null, groupIds: ["…"], importIds: ["…"], mode: "snapshot" });
if (error) {
  throw new Error(error.error.message);
}
console.log(data);

{
  "active": true,
  "alreadyEnrolled": 13,
  "enrolled": 412,
  "programId": "prg_b2n4x8mq1w7e9rk3v5tz0yc6",
  "senderIds": [
    "snd_pfh0haxfpzowht3oi213cqos"
  ],
  "suppressed": 4
}

{
  "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

Enroll people into a program

Authorizations

Headers

Path Parameters

Body

Response