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

Change a campaign: its settings, its pool, or its steps.

Steps are the whole ordered list; a changed step gets a new revision for messages not yet created.

PATCH/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}$
Header parameters
If-Matchstring

The version the change applies to, quoted as the ETag that carried it ("1790000000000000"), or *. A version that is no longer current answers 412 precondition_failed and changes nothing; without the header the change applies to whatever version is current.

Idempotency-Keystring

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

min length 1 · max length 128 · matches ^[!-~]+$
Request body
requiredapplication/json
namestring | null
scheduleScheduleInput | null
Show properties
One of:
ScheduleInput
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_atstring | null

No step runs before this instant; null removes it.

timezonestring | null

An IANA time zone, such as Europe/Madrid (default UTC).

null
null
sendersSendersInput | null
Show properties
One of:
SendersInput
identity_idsstring[] | null

The identities the campaign names (sid_…), at most 500; replaces the list.

on_sender_removedOnSenderRemoved | null
Show properties
One of:
OnSenderRemoved
string
null
null
tagsstring[] | null

Tags whose enabled identities join the pool, at most 20, each 1 to 50 characters.

null
null
stepsStepInput[] | null

The whole ordered list, at most 50: a step by id alone stays unchanged, by id with fields takes them, without id is new, and one left out is removed (refused once it has sent). Together the campaign's steps then, kept ones included, hold at most 1.5 MiB of names, prompts and templates.

Show properties
Array of StepInput
allocationAllocation | null
Show properties
One of:
Allocation
string
null
null
delay_secondsinteger<int32> | null

0 to 31,536,000 seconds after the previous step's message was sent (default 0).

idId_Step | null
Show properties
One of:
Id_Step
string
null
null
namestring | null

1 to 200 characters; required for a new step.

personalisation_promptstring | null

What the AI writes each message's snippets from, 1 to 4,000 characters; null removes it.

same_threadboolean | null

Continue the conversation's thread (default true).

variantsVariantInput[] | null

1 to 50 variants; required for a new step.

Show properties
Array of VariantInput
bccstring[] | null

Blind-copied on every message of the variant, at most 20.

ccstring[] | null

Copied on every message of the variant, at most 20.

htmlstring | null

The HTML body template, at most 256 KiB; required for a new variant.

idId_Variant | null
Show properties
One of:
Id_Variant
string
null
null
namestring | null

1 to 200 characters (default: a letter by position).

preheaderstring | null

The hidden preview text template, at most 1,000 characters; null removes it.

subjectstring | null

The subject template, 1 to 1,000 characters; required for a new variant.

weightinteger<int32> | null

The share under weighted allocation, 1 to 100 (default: the current weight, else 1).

winner_ruleWinnerRuleInput | null
Show properties
One of:
WinnerRuleInput
minimum_sampleinteger<int32> | null

1 to 1,000,000 messages per variant.

objectiveObjective | null
Show properties
One of:
Objective
string
null
null
observation_window_secondsinteger<int32> | null

1 to 31,536,000 seconds.

null
null
winner_variant_idstring | null

The variant the step now sends to everyone (var_…), one of its variants; null clears it.

stop_rulesStopRulesInput | null
Show properties
One of:
StopRulesInput
company_on_replyboolean | null
cooldown_hoursinteger<int32> | null

0 to 8,760 hours (default 72).

on_replyStopOnReply | null
Show properties
One of:
StopOnReply
string
null
null
null
null
trackingTrackingInput | null
Show properties
One of:
TrackingInput
clicksboolean | null
domain_idstring | null

A sending domain whose tracking host the links use (dom_…); null: the platform's.

opensboolean | null
null
null
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.

400

The body is not JSON, or If-Match is malformed (invalid_request).

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.

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

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, sender identity or tracking domain 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.

409

The campaign is archived, or a removed step has sent mail (invalid_state).

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.

412

If-Match names a version that is no longer current (precondition_failed); nothing changed.

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.

413

The body is larger than 1.5 MiB (payload_too_large).

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.

422

The body is invalid, a template does not parse, or the steps would hold more than 1.5 MiB; nothing changed.

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
Bodyapplication/json
Request
curl -X PATCH 'https://api.norbelys.com/v1/campaigns/cmp_0190f8a2b4c87a10b6d2e4f6a8c0e2f4' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "senders": {
    "tags": [
      "outbound",
      "emea"
    ]
  },
  "steps": [
    {
      "id": "stp_0190f8a2b4c87a10b6d2e4f6a8c0e2f4"
    },
    {
      "delay_seconds": 259200,
      "id": "stp_0190f8a2b4c87a10b6d2e4f6a8c0e2f5"
    }
  ]
}'
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
}