Update a sequence draft

$ lightfield sequence update-draft

POST/v1/sequences/{id}/draft

Saves changes to the sequence’s open draft, or opens one from the published version when none is open. Only the fields sent are changed; definition.steps replaces the whole step list. Changes take effect when the draft is published. See Using sequences with the API for the draft and version model.

Returns 409 when expectedVersion is not the open draft’s version, or for a steps save while the draft has unfinished edits in Lightfield; retrieve the draft and retry. A refused save changes nothing: 400 invalid_configuration lists every problem under issues, 400 referenced_resource_missing names a reviewer or sender that does not exist, and a value outside its field’s documented bounds returns 400 naming the field in param. See Sequence errors.

Required scope: sequences:update

Rate limit category: Write

ParametersExpand Collapse

--id: string

Unique identifier of the sequence.

--definition: optional object { description, messaging, pacing, 3 more }

Fields to change. Omitted fields are unchanged.

--expected-version: optional string

The open draft’s version as last read. Required when a draft is open; omit it only when none is, to start one from the published version.

--name: optional string

Name of the sequence.

--reviewers: optional object { add, remove }

Extra members who may approve this sequence’s FOR_REVIEW messages before they send. The sending member and the sequence’s creator always review, whether or not they are listed. Changes the list by adding and removing members; omit to keep it.

--senders: optional object { add, remove }

The senders this sequence sends from; new contacts rotate across them. Changes the list by adding and removing senders; omit to keep it.

ReturnsExpand Collapse

sequence_update_draft_response: object { channels, definition, name, 6 more }

channels: array of "EMAIL" or "LINKEDIN"

Channels the draft’s steps send on.

"EMAIL"

"LINKEDIN"

definition: object { description, messaging, pacing, 3 more }

The draft configuration, in the same shape as a published definition.

description: string

What this version of the sequence is for.

messaging: object { callToAction, persona, trigger, valueProp }

Messaging inputs that frame every step.

callToAction: string

What the recipient is asked to do.

persona: string

Who the sequence targets.

trigger: string

Why the outreach is timely.

valueProp: string

The value proposition.

pacing: object { EMAIL, LINKEDIN_INVITE, LINKEDIN_MESSAGE }

How the whole sequence paces each step type it sends, keyed by sequence step type.

EMAIL: object { dailyLimit }

Email steps.

dailyLimit: number

Most sends of this step type across the whole sequence in any rolling 24 hours, or null when the sequence sets no daily cap. Workspace and sender limits still apply.

LINKEDIN_INVITE: object { dailyLimit }

LinkedIn connection requests.

dailyLimit: number

Most sends of this step type across the whole sequence in any rolling 24 hours, or null when the sequence sets no daily cap. Workspace and sender limits still apply.

LINKEDIN_MESSAGE: object { dailyLimit }

LinkedIn messages.

dailyLimit: number

Most sends of this step type across the whole sequence in any rolling 24 hours, or null when the sequence sets no daily cap. Workspace and sender limits still apply.

priority: "HIGH" or "NORMAL"

Send priority relative to other sequences.

"HIGH"

"NORMAL"

sendWindow: object { daysOfWeek, endHour, startHour, timezone }

When the sequence may send.

daysOfWeek: array of number

Days sends may go out, 0 = Sunday.

endHour: number

Local hour sends stop, exclusive (1–24).

startHour: number

First local hour sends may go out (0–23).

timezone: string

IANA timezone of the window.

steps: array of object { id, deliveryMode, mode, 3 more } or object { id, deliveryMode, includeNote, 4 more } or object { id, deliveryMode, mode, 3 more } or 3 more

Email, LinkedIn and wait steps in execution order.

union_member_0: object { id, deliveryMode, mode, 3 more }

id: string

Step identifier, referenced by enrollment currentStepId and message sequenceStepId.

deliveryMode: "AUTO" or "FOR_REVIEW"

AUTO sends without manual approval, subject to the send window and limits; FOR_REVIEW requires a person to approve the draft before sending.

"AUTO"

"FOR_REVIEW"

mode: "AGENT"

How each message is written: AGENT composes it from prompt; TEMPLATE sends template to every contact, with its variables filled in.

"AGENT"

Display name of the step.

prompt: string

Instructions the agent follows when composing this message.

type: "EMAIL" or "LINKEDIN_MESSAGE"

Step type.

"EMAIL"

"LINKEDIN_MESSAGE"

union_member_1: object { id, deliveryMode, includeNote, 4 more }

id: string

Step identifier, referenced by enrollment currentStepId and message sequenceStepId.

deliveryMode: "AUTO" or "FOR_REVIEW"

AUTO sends without manual approval, subject to the send window and limits; FOR_REVIEW requires a person to approve the draft before sending.

"AUTO"

"FOR_REVIEW"

includeNote: boolean

Whether the connection request carries a note. A step authored before this setting existed reads as true.

mode: "AGENT"

How each message is written: AGENT composes it from prompt; TEMPLATE sends template to every contact, with its variables filled in.

"AGENT"

Display name of the step.

prompt: string

Instructions the agent follows when composing this message.

type: "LINKEDIN_INVITE"

Step type.

"LINKEDIN_INVITE"

union_member_2: object { id, deliveryMode, mode, 3 more }

id: string

Step identifier, referenced by enrollment currentStepId and message sequenceStepId.

deliveryMode: "AUTO" or "FOR_REVIEW"

AUTO sends without manual approval, subject to the send window and limits; FOR_REVIEW requires a person to approve the draft before sending.

"AUTO"

"FOR_REVIEW"

mode: "TEMPLATE"

How each message is written: AGENT composes it from prompt; TEMPLATE sends template to every contact, with its variables filled in.

"TEMPLATE"

Display name of the step.

The email every contact receives.

body: string

Email body as Markdown, without the sign-off or signature, which are added when the message is written. Each {{ }} is a variable filled in per contact, with a fallback for a contact missing the value; a field variable names the field by the ad_ ID the field-definitions endpoints list.

subject: string

Plain-text subject line. Each {{ }} is a variable filled in per contact, with a fallback for a contact missing the value; a field variable names the field by the ad_ ID the field-definitions endpoints list.

type: "EMAIL"

Step type.

"EMAIL"

union_member_3: object { id, deliveryMode, mode, 3 more }

id: string

Step identifier, referenced by enrollment currentStepId and message sequenceStepId.

deliveryMode: "AUTO" or "FOR_REVIEW"

AUTO sends without manual approval, subject to the send window and limits; FOR_REVIEW requires a person to approve the draft before sending.

"AUTO"

"FOR_REVIEW"

mode: "TEMPLATE"

How each message is written: AGENT composes it from prompt; TEMPLATE sends template to every contact, with its variables filled in.

"TEMPLATE"

Display name of the step.

The message every contact receives; for an invite, its connection note, sent only with includeNote.

body: string

Plain-text message. Each {{ }} is a variable filled in per contact, with a fallback for a contact missing the value; a field variable names the field by the ad_ ID the field-definitions endpoints list.

type: "LINKEDIN_MESSAGE"

Step type.

"LINKEDIN_MESSAGE"

union_member_4: object { id, deliveryMode, includeNote, 4 more }

id: string

Step identifier, referenced by enrollment currentStepId and message sequenceStepId.

deliveryMode: "AUTO" or "FOR_REVIEW"

AUTO sends without manual approval, subject to the send window and limits; FOR_REVIEW requires a person to approve the draft before sending.

"AUTO"

"FOR_REVIEW"

includeNote: boolean

Whether the connection request carries a note. A step authored before this setting existed reads as true.

mode: "TEMPLATE"

How each message is written: AGENT composes it from prompt; TEMPLATE sends template to every contact, with its variables filled in.

"TEMPLATE"

Display name of the step.

The message every contact receives; for an invite, its connection note, sent only with includeNote.

body: string

type: "LINKEDIN_INVITE"

Step type.

"LINKEDIN_INVITE"

union_member_5: object { id, duration, type, unit }

id: string

Step identifier.

duration: number

Length of the wait.

type: "WAIT" or "WAIT_FOR_CONNECTION"

WAIT pauses for a fixed time; WAIT_FOR_CONNECTION waits up to that long for a LinkedIn invite to be accepted.

"WAIT"

"WAIT_FOR_CONNECTION"

unit: "DAY" or "MINUTE"

Unit of duration.

"DAY"

"MINUTE"

Name the sequence takes when the draft is published.

publishWarnings: array of object { code, message, severity, stepIds }

What publishing this draft would change for contacts already in the sequence; empty when nothing is affected. Before the first publish, the only possible warning is a proposed sender that was archived and would be left off.

code: "delay_shortened" or "delay_lengthened" or "connection_wait_shortened" or 18 more

What publishing would change.

"delay_shortened"

"delay_lengthened"

"connection_wait_shortened"

"connection_wait_lengthened"

"send_schedule_changed"

"send_configuration_changed"

"send_priority_changed"

"senders_changed"

"email_sender_pool_emptied"

"linkedin_account_pool_emptied"

"assigned_sender_removed"

"delivery_became_automatic"

"invite_note_enabled"

"invite_note_disabled"

"step_inserted"

"automatic_send_step_inserted"

"step_removed"

"step_type_changed"

"step_order_changed"

"full_identity_rewrite"

"low_identity_overlap"

message: string

What would change, in plain language.

severity: "warning" or "destructive"

destructive when contacts already in the sequence may skip, repeat or receive a step they would not have; warning otherwise.

"warning"

"destructive"

stepIds: array of string

The steps involved; empty for a sequence-wide change.

reviewers: array of object { id, objectType }

Extra members who may approve this sequence’s FOR_REVIEW messages before they send. The sending member and the sequence’s creator always review, whether or not they are listed.

id: string

ID of the member.

objectType: "member"

Always member.

"member"

senders: array of object { id, objectType }

The senders this draft will publish; new contacts rotate across them. Until a save changes it, this is the sequence’s live list. An archived sender stays listed but never sends; any change to the list drops it.

id: string

ID of the sender.

objectType: "sender"

Always sender.

"sender"

sequenceId: string

The sequence this draft belongs to.

updatedAt: string

When the draft last changed.

version: string

Opaque token for the current state of the draft. Send it as expectedVersion on the next save, publish or discard; it changes whenever anyone edits the draft.

Update a sequence draft

lightfield sequence update-draft \
  --api-key 'My API Key' \
  --id id

{
  "channels": [
    "EMAIL"
  ],
  "definition": {
    "description": "description",
    "messaging": {
      "callToAction": "callToAction",
      "persona": "persona",
      "trigger": "trigger",
      "valueProp": "valueProp"
    },
    "pacing": {
      "EMAIL": {
        "dailyLimit": -9007199254740991
      },
      "LINKEDIN_INVITE": {
        "dailyLimit": -9007199254740991
      },
      "LINKEDIN_MESSAGE": {
        "dailyLimit": -9007199254740991
      }
    },
    "priority": "HIGH",
    "sendWindow": {
      "daysOfWeek": [
        -9007199254740991
      ],
      "endHour": -9007199254740991,
      "startHour": -9007199254740991,
      "timezone": "timezone"
    },
    "steps": [
      {
        "id": "id",
        "deliveryMode": "AUTO",
        "mode": "AGENT",
        "name": "name",
        "prompt": "prompt",
        "type": "EMAIL"
      }
    ]
  },
  "name": "name",
  "publishWarnings": [
    {
      "code": "delay_shortened",
      "message": "message",
      "severity": "warning",
      "stepIds": [
        "string"
      ]
    }
  ],
  "reviewers": [
    {
      "id": "x",
      "objectType": "member"
    }
  ],
  "senders": [
    {
      "id": "x",
      "objectType": "sender"
    }
  ],
  "sequenceId": "sequenceId",
  "updatedAt": "updatedAt",
  "version": "version"
}

Returns Examples

{
  "channels": [
    "EMAIL"
  ],
  "definition": {
    "description": "description",
    "messaging": {
      "callToAction": "callToAction",
      "persona": "persona",
      "trigger": "trigger",
      "valueProp": "valueProp"
    },
    "pacing": {
      "EMAIL": {
        "dailyLimit": -9007199254740991
      },
      "LINKEDIN_INVITE": {
        "dailyLimit": -9007199254740991
      },
      "LINKEDIN_MESSAGE": {
        "dailyLimit": -9007199254740991
      }
    },
    "priority": "HIGH",
    "sendWindow": {
      "daysOfWeek": [
        -9007199254740991
      ],
      "endHour": -9007199254740991,
      "startHour": -9007199254740991,
      "timezone": "timezone"
    },
    "steps": [
      {
        "id": "id",
        "deliveryMode": "AUTO",
        "mode": "AGENT",
        "name": "name",
        "prompt": "prompt",
        "type": "EMAIL"
      }
    ]
  },
  "name": "name",
  "publishWarnings": [
    {
      "code": "delay_shortened",
      "message": "message",
      "severity": "warning",
      "stepIds": [
        "string"
      ]
    }
  ],
  "reviewers": [
    {
      "id": "x",
      "objectType": "member"
    }
  ],
  "senders": [
    {
      "id": "x",
      "objectType": "sender"
    }
  ],
  "sequenceId": "sequenceId",
  "updatedAt": "updatedAt",
  "version": "version"
}