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

Start a campaign from `draft` or `paused`: it is `materialising` until its job makes it `active` and creates the messages already due.

POST/v1/campaigns/{id}/start
Authorization
AuthorizationBearer token · headerrequired

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

Path parameters
idId_Campaignrequired

The campaign id (cmp_…).

matches ^cmp_[0-9a-f]{32}$
Header parameters
Idempotency-Keystringrequired

A stable key for this logical request; reuse it when retrying.

min length 1 · max length 128 · matches ^[!-~]+$
Responses
200

The campaign, materialising.

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.

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:write.

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.

404

No such campaign in this workspace.

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.

409

The campaign is not draft or paused, or has no step with a variant (invalid_state).

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 POST 'https://api.norbelys.com/v1/campaigns/cmp_0190f8a2b4c87a10b6d2e4f6a8c0e2f4/start' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Idempotency-Key: string'
Response
{
  "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
}