Skip to content
Norbelys
Esc
↑↓navigate↵open⌘Jpreview

List the workspace's campaigns, newest first by default; the variants' bodies are left out.

GET/v1/campaigns
Authorization
AuthorizationBearer token · headerrequired

An API key (nb_live_…, nb_test_…), a workspace token (nbs_…) or a CLI token (nbc_…).

Query parameters
limitinteger<int64>

Campaigns per page, 1 to 100 (default 20).

cursorstring

The next_cursor of the previous page.

orderstring

desc (default) or asc.

includestring

total_count adds an exact count up to 10,000.

statusCampaignStatus

Campaigns in this status.

Allowed:draftmaterialisingactivepausedcompletedarchived
qstring

A prefix of the name, ignoring case.

Responses
200

A page of campaigns.

dataobject[]required

At most limit rows, 100 at most.

max items 100
Show properties
Array of object
created_atTimestamprequired
idId_Campaignrequired
matches ^cmp_[0-9a-f]{32}$
last_errorCampaignLastError | null
Show properties
One of:
CampaignLastError
atTimestamprequired
codestringrequired

no_sender or invalid. New codes may be added.

detailstringrequired
null
null
namestringrequired
scheduleScheduleObjectrequired

When the campaign sends.

Show properties
send_windowSendWindow | null
Show properties
One of:
SendWindow
daysinteger<int32>[]required

The days of the week, 1 (Monday) to 7 (Sunday), each once, in order.

endstringrequired

The closing time, HH:MM, after the opening; 24:00 closes at midnight.

startstringrequired

The opening time, HH:MM.

null
null
start_atTimestamp | null
Show properties
One of:
Timestamp
string<date-time>
null
null
timezonestringrequired

The IANA time zone of the send window.

sendersSendersObjectrequired

The campaign's pool of senders.

Show properties
identity_idsId_SenderIdentity[]required

The identities the campaign names (sid_…).

on_sender_removedOnSenderRemovedrequired

What a campaign does with a conversation whose sender left its pool (campaigns.on_sender_removed).

Allowed:reassignstop
tagsstring[]required

Every enabled identity carrying one of these tags joins the pool, as it is when a sender is assigned.

statsStatsObjectrequired

The campaign's counters, from the analytics rollup.

Show properties
bouncedinteger<int64>required
clickedinteger<int64>required
computed_atTimestamp | null
Show properties
One of:
Timestamp
string<date-time>
null
null
openedinteger<int64>required
repliedinteger<int64>required
sentinteger<int64>required
unsubscribedinteger<int64>required
statusCampaignStatusrequired

A campaign's lifecycle (campaigns.status).

Allowed:draftmaterialisingactivepausedcompletedarchived
stepsStepObject[]required

The steps in order, with their variants (a list leaves out the variants' bodies).

max items 20
Show properties
Array of StepObject
allocationAllocationrequired

How a step revision assigns its variants (step_revisions.allocation).

Allowed:balancedweightedautomatic
delay_secondsinteger<int32>required

How long after the previous step's message was sent this step is due; the first step runs when a person is enrolled, so its delay is not used.

idId_Steprequired
matches ^stp_[0-9a-f]{32}$
namestringrequired
personalisation_promptstring | null

What the AI writes each message's snippets from (the variables namespace); null: the templates alone.

positioninteger<int32>required

1 for the first step.

revisioninteger<int32>required

The current revision: what messages created now are made from.

same_threadbooleanrequired

Whether the step's message continues the conversation's thread (a reply to the previous message) or starts a new one.

variantsVariantObject[]required

The variants this revision offers.

max items 10
Show properties
Array of VariantObject
bccstring[]required
ccstring[]required
idId_Variantrequired
matches ^var_[0-9a-f]{32}$
namestringrequired
preheaderstring | null

The hidden preview text template.

subjectstringrequired

The subject template.

versioninteger<int32>required

The version of its content the step's revision offers.

weightinteger<int32>required

Its share under weighted allocation, 1 to 100.

winnerWinnerObject | null
Show properties
One of:
WinnerObject
selected_atTimestamprequired
selected_bystringrequired

automatic, or the user who chose it (usr_…).

variant_idId_Variantrequired
matches ^var_[0-9a-f]{32}$
null
null
winner_ruleWinnerRuleObjectrequired

When an automatic step names its winner.

Show properties
minimum_sampleinteger<int32>required

The messages every variant must have sent first.

objectiveObjectiverequired

What a test of variants is decided by (step_revisions.ranking_objective).

Allowed:opensclicksreplies
observation_window_secondsinteger<int32>required

How long after the revision was published the results are read.

stop_rulesStopRulesObjectrequired

When an enrollment stops before its last step.

Show properties
company_on_replybooleanrequired

Whether a reply also stops this campaign's enrollments of people at the same email domain (the same company).

cooldown_hoursinteger<int32>required

A new enrollment's first step waits until this many hours have passed since the person's last campaign message from the workspace.

on_replyStopOnReplyrequired

Which enrollments a person's reply stops (campaigns.stop_on_reply).

Allowed:allcampaignnone
trackingTrackingObjectrequired

What the campaign's messages track.

Show properties
clicksbooleanrequired
domain_idId_SendingDomain | null
Show properties
One of:
Id_SendingDomain
string
null
null
opensbooleanrequired
updated_atTimestamprequired
versioninteger<int64>required

The version an update's If-Match names.

metaMetarequired

The page metadata.

Show properties
has_morebooleanrequired
next_cursorstring | null
total_countinteger<int64> | null

With ?include=total_count: exact up to 10,000.

total_count_cappedboolean | null

With ?include=total_count: true when the count stopped at 10,000.

400

The cursor is not valid for this request.

codestringrequired

The code from the closed registry; programs branch on it, never on the text. New codes may be added.

detailstringrequired

What went wrong, for a person; never an internal cause.

errorsFieldError[]

With validation_failed only: every invalid field.

Show properties
Array of FieldError
codestringrequired

What is wrong (required, range, length, format, invalid, …).

detailstringrequired

A safe, human-readable explanation.

pointerstringrequired

RFC 6901 pointer into the body, or ?name for a query parameter.

instancestringrequired

The request's path.

request_idstringrequired

The request's id, also in X-Request-Id: what support needs to find the request.

retry_afterinteger<int64> | null

With 429 and 503: the seconds to wait, as in Retry-After.

min 0
statusinteger<int32>required

The HTTP status.

min 0
titlestringrequired

Fixed per code.

typestringrequired

https://docs.norbelys.com/errors/<code>, a page that explains the code.

401

No valid credential.

codestringrequired

The code from the closed registry; programs branch on it, never on the text. New codes may be added.

detailstringrequired

What went wrong, for a person; never an internal cause.

errorsFieldError[]

With validation_failed only: every invalid field.

Show properties
Array of FieldError
codestringrequired

What is wrong (required, range, length, format, invalid, …).

detailstringrequired

A safe, human-readable explanation.

pointerstringrequired

RFC 6901 pointer into the body, or ?name for a query parameter.

instancestringrequired

The request's path.

request_idstringrequired

The request's id, also in X-Request-Id: what support needs to find the request.

retry_afterinteger<int64> | null

With 429 and 503: the seconds to wait, as in Retry-After.

min 0
statusinteger<int32>required

The HTTP status.

min 0
titlestringrequired

Fixed per code.

typestringrequired

https://docs.norbelys.com/errors/<code>, a page that explains the code.

403

The credential lacks campaigns:read.

codestringrequired

The code from the closed registry; programs branch on it, never on the text. New codes may be added.

detailstringrequired

What went wrong, for a person; never an internal cause.

errorsFieldError[]

With validation_failed only: every invalid field.

Show properties
Array of FieldError
codestringrequired

What is wrong (required, range, length, format, invalid, …).

detailstringrequired

A safe, human-readable explanation.

pointerstringrequired

RFC 6901 pointer into the body, or ?name for a query parameter.

instancestringrequired

The request's path.

request_idstringrequired

The request's id, also in X-Request-Id: what support needs to find the request.

retry_afterinteger<int64> | null

With 429 and 503: the seconds to wait, as in Retry-After.

min 0
statusinteger<int32>required

The HTTP status.

min 0
titlestringrequired

Fixed per code.

typestringrequired

https://docs.norbelys.com/errors/<code>, a page that explains the code.

422

A parameter is invalid.

codestringrequired

The code from the closed registry; programs branch on it, never on the text. New codes may be added.

detailstringrequired

What went wrong, for a person; never an internal cause.

errorsFieldError[]

With validation_failed only: every invalid field.

Show properties
Array of FieldError
codestringrequired

What is wrong (required, range, length, format, invalid, …).

detailstringrequired

A safe, human-readable explanation.

pointerstringrequired

RFC 6901 pointer into the body, or ?name for a query parameter.

instancestringrequired

The request's path.

request_idstringrequired

The request's id, also in X-Request-Id: what support needs to find the request.

retry_afterinteger<int64> | null

With 429 and 503: the seconds to wait, as in Retry-After.

min 0
statusinteger<int32>required

The HTTP status.

min 0
titlestringrequired

Fixed per code.

typestringrequired

https://docs.norbelys.com/errors/<code>, a page that explains the code.

Try it
Server
Authorization
Parameters
Request
curl -X GET 'https://api.norbelys.com/v1/campaigns' \
  -H 'Authorization: Bearer YOUR_TOKEN'
Response
{
  "data": [
    {
      "created_at": "2019-08-24T14:15:22Z",
      "id": "cmp_0190f8a2b4c87a10b6d2e4f6a8c0e2f4",
      "last_error": {
        "at": "2019-08-24T14:15:22Z",
        "code": "string",
        "detail": "string"
      },
      "name": "string",
      "schedule": {
        "send_window": {
          "days": [
            0
          ],
          "end": "string",
          "start": "string"
        },
        "start_at": "2019-08-24T14:15:22Z",
        "timezone": "string"
      },
      "senders": {
        "identity_ids": [
          "sid_0190f8a2b4c87a10b6d2e4f6a8c0e2f4"
        ],
        "on_sender_removed": "reassign",
        "tags": [
          "string"
        ]
      },
      "stats": {
        "bounced": 0,
        "clicked": 0,
        "computed_at": "2019-08-24T14:15:22Z",
        "opened": 0,
        "replied": 0,
        "sent": 0,
        "unsubscribed": 0
      },
      "status": "draft",
      "steps": [
        {
          "allocation": "balanced",
          "delay_seconds": 0,
          "id": "stp_0190f8a2b4c87a10b6d2e4f6a8c0e2f4",
          "name": "string",
          "personalisation_prompt": "string",
          "position": 0,
          "revision": 0,
          "same_thread": true,
          "variants": [
            {
              "html": "string",
              "text": "string",
              "bcc": [
                "string"
              ],
              "cc": [
                "string"
              ],
              "id": "var_0190f8a2b4c87a10b6d2e4f6a8c0e2f4",
              "name": "string",
              "preheader": "string",
              "subject": "string",
              "version": 0,
              "weight": 0
            }
          ],
          "winner": {
            "selected_at": "2019-08-24T14:15:22Z",
            "selected_by": "string",
            "variant_id": "var_0190f8a2b4c87a10b6d2e4f6a8c0e2f4"
          },
          "winner_rule": {
            "minimum_sample": 0,
            "objective": "opens",
            "observation_window_seconds": 0
          }
        }
      ],
      "stop_rules": {
        "company_on_reply": true,
        "cooldown_hours": 0,
        "on_reply": "all"
      },
      "tracking": {
        "clicks": true,
        "domain_id": "dom_0190f8a2b4c87a10b6d2e4f6a8c0e2f4",
        "opens": true
      },
      "updated_at": "2019-08-24T14:15:22Z",
      "version": 0
    }
  ],
  "meta": {
    "has_more": true,
    "next_cursor": "string",
    "total_count": 0,
    "total_count_capped": true
  }
}