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

Retrieve a campaign with its steps and their variants' bodies.

Its enrollments are counted as it is read (enrollments): how many are in each status, how many live ones are at each step, and when the campaign’s next email may go.

GET/v1/campaigns/{id}
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}$
Responses
200

The campaign.

created_atTimestamprequired
enrollmentsEnrollmentSummary | null
Show properties
One of:
EnrollmentSummary
activeinteger<int64>required

Live enrollments whose steps run.

completedinteger<int64>required

Enrollments that went through the campaign's last step.

failedinteger<int64>required

Enrollments that ended because a step could not be sent.

next_run_atTimestamp | null
Show properties
One of:
Timestamp
string<date-time>
null
null
pausedinteger<int64>required

Live enrollments held for now: their steps wait.

repliedinteger<int64>required

Enrollments that ended because the person replied.

stepsStepEnrollments[]required

Every step of the campaign, in order, with its live enrollments (active or paused): those whose email from this step is due or on its way. A live enrollment whose step was removed counts in its status but at no step, until the next pass completes it.

max items 50
Show properties
Array of StepEnrollments
liveinteger<int64>required

Live enrollments (active or paused) at this step now.

step_idId_Steprequired
matches ^stp_[0-9a-f]{32}$
stoppedinteger<int64>required

Enrollments stopped by a person, a stop rule, a suppression or a sender that left the pool.

null
null
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 50
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 50
Show properties
Array of VariantObject
bccstring[]required
ccstring[]required
htmlstring

The HTML body template: shown on a campaign retrieved alone, absent from a list (bodies can be large, and a list shows many variants).

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.

codeProblemCoderequired

The closed registry of problem codes: programs branch on a problem's code, never on its text. A code may be added, never repurposed.

Allowed:invalid_requestunauthorizedforbiddensession_requirednot_foundarchivedmethod_not_allowedconflictinvalid_stateidempotency_in_progressprecondition_failedpayload_too_largeunsupported_media_typevalidation_failedidempotency_mismatchsuppressedcaptcha_failedinsufficient_scoperate_limitedquota_exceededinternal_errorservice_unavailabletimeout
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.

codeProblemCoderequired

The closed registry of problem codes: programs branch on a problem's code, never on its text. A code may be added, never repurposed.

Allowed:invalid_requestunauthorizedforbiddensession_requirednot_foundarchivedmethod_not_allowedconflictinvalid_stateidempotency_in_progressprecondition_failedpayload_too_largeunsupported_media_typevalidation_failedidempotency_mismatchsuppressedcaptcha_failedinsufficient_scoperate_limitedquota_exceededinternal_errorservice_unavailabletimeout
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.

codeProblemCoderequired

The closed registry of problem codes: programs branch on a problem's code, never on its text. A code may be added, never repurposed.

Allowed:invalid_requestunauthorizedforbiddensession_requirednot_foundarchivedmethod_not_allowedconflictinvalid_stateidempotency_in_progressprecondition_failedpayload_too_largeunsupported_media_typevalidation_failedidempotency_mismatchsuppressedcaptcha_failedinsufficient_scoperate_limitedquota_exceededinternal_errorservice_unavailabletimeout
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/cmp_0190f8a2b4c87a10b6d2e4f6a8c0e2f4' \
  -H 'Authorization: Bearer YOUR_TOKEN'
Response
{
  "created_at": "2019-08-24T14:15:22Z",
  "enrollments": {
    "active": 0,
    "completed": 0,
    "failed": 0,
    "next_run_at": "2019-08-24T14:15:22Z",
    "paused": 0,
    "replied": 0,
    "steps": [
      {
        "live": 0,
        "step_id": "stp_0190f8a2b4c87a10b6d2e4f6a8c0e2f4"
      }
    ],
    "stopped": 0
  },
  "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": [
        {
          "bcc": [
            "string"
          ],
          "cc": [
            "string"
          ],
          "html": "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
}