Docs
OverviewPlatformPlatform APIA2P Messaging API
AI & MCP
Open dashboard
OverviewPlatformPlatform APIA2P Messaging API
AI & MCP
  • Overview
  • Introduction
  • Create an account
  • Choose your API
  • Authentication
  • AI & MCP
Product API
  • Guide
  • Quickstart
    • API tokens
    • Connected apps (OAuth)
    • Project readiness
    • Channel readiness
    • Senders
    • Attention
    • Recommendations
    • Overview
    • Contacts and attributes
    • Events
    • Query filter
    • Event query filter
    • Probes
    • Counting and retrieval
    • Segments
    • Overview
    • Creating a draft
    • Editing a draft
    • Audience targeting
    • Message content
    • Dates and scheduling
    • Reading campaigns
    • Estimating and deleting
    • OverviewBeta
    • Templates
    • Creating and editing drafts
    • Triggers and exits
    • Nodes
    • Delays and waits
    • Overview
    • Statistics catalog
    • Building queries
    • Conversions & revenue
    • Reading results
    • Flow reports
    • Rate limits
    • Errors
  • Full API Reference
Ingest API
  • Guide
  • Quickstart
  • Authentication
  • Rate limits
  • Errors
  • Best practices
  • Full API Reference
Further reading
  • Query Filter
DashboardSupportinstasent.com

Platform API · Product API · Campaigns

Editing a draft

The PATCH contract for campaign drafts: which campaigns can still be changed, how expectedUpdatedAt guards against overwriting someone else's edit, what each field of the body replaces or merges, and the errors an integration has to handle.

On this page▾
  • Which campaigns can be edited
  • Read, change, write back
  • What each field does
  • The audience goes whole
  • The channel block merges key by key
  • The response
  • Errors
  • What's next

A draft rarely comes out right in one call. A marketer asks for a different segment, the copy needs a second pass, the sender was the wrong one. Editing changes the campaign you already have and keeps its id, so links, flows and anything else that points at it keep working. Posting the campaign again is not an edit: it creates a second one.

PATCH/v1/project/{project}/campaign/{id}

Edit a campaign that is not prepared yet.

An edit never arms, schedules or sends anything, and spends no balance. It does what an edit in the dashboard does: the campaign goes back to draft and loses its estimate, so the counts and prices are cleared and you estimate it again once it is ready. The endpoint takes the same PROJECT_CAMPAIGN_WRITE scope as creation and sits in the same medium rate-limit class — see Rate limits.

Which campaigns can be edited

Only a campaign nobody has prepared yet. Everything else answers 409 Conflict and changes nothing:

The campaign isWhat the edit does
draft, preview, estimated, quotedApplies. A quoted campaign loses its quote along with the estimate.
estimating, quoting, preparing, unpreparing, continuing, resuming409 asking you to wait: a worker is moving the campaign. Read it again when the worker finishes and retry if it is still editable.
prepared, scheduled or any later status409. A person has already confirmed it; review it in the dashboard if it needs changes.
An A/B test, or a campaign that is not a standard one409, whatever the status.

See Statuses and phases for what each status means.

Read, change, write back

Two writers can work on the same draft: your integration and a person in the dashboard. The edit protects each from silently overwriting the other with expectedUpdatedAt, which is required:

  1. 1

    Read the campaign

    GET /campaign/{id} and keep its updatedAt.

  2. 2

    Send only what changes

    expectedUpdatedAt set to that value, plus at least one field to change.

  3. 3

    Keep the new updatedAt

    The response carries the campaign with a new updatedAt. Use it for the next edit.

If the campaign changed since you read it, the edit answers 409 and writes nothing. Read it again, reapply your change on top of what you read, and retry. The comparison is to the second, so send the value exactly as a read returned it.

curl -X PATCH "$BASE/campaign/68b0f2a4e5a6b7c8d9e0f1a2" \
  -H "Authorization: Bearer $INSTASENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "expectedUpdatedAt": "2026-11-18T10:15:00+01:00",
    "title": "Black Friday, second wave",
    "date": "2026-11-28T09:30:00+01:00"
  }'

What each field does

The body uses the vocabulary of creating a draft: every field has the same meaning, format and limits. The difference is that a field you send replaces its part of the campaign, and a field you omit stays as it is, including what only the dashboard sets, such as the send interval and local time.

expectedUpdatedAtstringrequired

The updatedAt of the campaign as you last read it.

title, emoji, descriptionstring

Each one replaced when sent.

datestring | null

Moves the calendar anchor, with an optional time in the same request. null removes it. A time sent without date is refused with invalid-date. As on creation, nothing is scheduled by setting it — see Dates and scheduling.

audienceobject

Replaced whole. See The audience goes whole.

message, sender, fallback, compliance, translateTo

The channel block, merged key by key into the campaign's current channel. See The channel block merges key by key.

channelstring

Accepted only when it repeats the campaign's channel. Anything else is refused with channel-not-editable: a campaign never changes channel, and a different channel is a different campaign.

The audience goes whole

audience replaces both lists at once, so it always carries its include — ["_all"] targets everyone — together with the exclusions you want to keep. An exclude you leave out clears the current exclusions. This is stricter than creation on purpose: there a missing include means everyone, but on an edit it would turn "add an exclusion" into a retarget to the whole audience.

{
  "expectedUpdatedAt": "2026-11-18T10:15:00+01:00",
  "audience": {
    "include": ["vip-customers"],
    "exclude": ["recently-messaged", "bought-this-week"]
  }
}

The entries are segment UIDs and inline filters, validated exactly as on creation. Sending audience selects each segment again: the campaign copies the segment's current conditions, even for a segment it already had, so this is how a draft picks up changes made to a segment since it was created. An edit that omits audience keeps the conditions the campaign already has. See Segments are copied when selected and Audience targeting.

The channel block merges key by key

message, sender, fallback, compliance and translateTo each change only their own part of the channel. Changing the sender keeps the copy, and changing the copy keeps the sender, the consent policy, the fallback and the translations already written. On RCS that includes rich content you did not send back: cards, carousels, media and buttons stay as a person left them.

messageobject

Send it only to change the copy. The copy you send replaces the current one whole, buttons included: a text (with its suggestions on RCS) or, on RCS, a template, never both. A message never empties the copy: it must carry a non-empty text, a template, or only the language that translateTo needs, and anything else is refused with invalid-message. See Message content.

senderstring

The new sender. A translation that used the old sender follows it; one that has its own sender keeps it.

fallbackobject

RCS only. New copy for the SMS fallback the campaign already has. As on creation, it needs its text. Its sender stays unless you name fallback.sender, or the edit changes the RCS agent (see below). A fallback is fixed when the campaign is created: an edit neither adds one nor removes one, and trying either is refused with fallback-not-supported.

compliancestring

basic, no-opt-out or opt-in, the policies the dashboard offers (the legacy opt-out is still read as no-opt-out). Anything else is refused with invalid-message. See Consent policy.

translateToarray

The full set of declared languages, with message.language alongside as on creation. A language that stays declared keeps the translation already written for it, a new one is declared empty, and one you leave out is removed. See Declaring other languages.

On RCS, the fallback follows the agent. When an edit changes the RCS sender and does not name fallback.sender, a fallback still on the old agent's SMS sender (or on none) moves to the SMS sender configured on the new agent, when it has one, as it would have on creation. A fallback that somebody set to a different SMS sender keeps it.

Multi-language campaigns are a paid feature. An edit that declares languages on a campaign that had none, without a subscription that includes them, answers 409 Conflict and writes nothing. A campaign that already carries languages stays editable after a downgrade.

The response

A successful edit returns 200 OK with the campaign under entity, back in draft and with a new updatedAt, and the same metadata as creation: warnings about the draft as edited and, only when the request carried message.template, ignoredTemplateFields.

The sender warnings are reported only when the edit touched the sender. A draft that already had no-default-sender and is edited for its title does not report it again, so read the campaign if you need its full state.

Errors

StatusWhen
400The body is not a JSON object, expectedUpdatedAt is missing or not a date, or there is no field to change.
404No campaign with that id.
409The campaign is not editable or a worker is moving it (see Which campaigns can be edited), it changed since you read it, or the edit turns multi-language on without the subscription.
422The same validation as creation, with the stable code in errorCode and the reason in errorMessage — see Errors — plus the cases below.

Codes that are specific to an edit, or that an edit reaches in a new way:

errorCodeWhat happenedWhat to do
channel-not-editablechannel names a different channel from the campaign's.Drop channel, or create a new campaign on the other channel.
unknown-segmentaudience is not an object, or it has no include.Send the whole audience: include (["_all"] for everyone) and exclude.
fallback-not-supportedThe edit tries to add a fallback to a campaign without one, or to remove the one it has.Edit the existing fallback's copy only; anything else is a change for the dashboard.
invalid-messageA message that would empty the copy, a fallback with no text, or a consent policy outside basic, no-opt-out and opt-in.See The channel block merges key by key.
invalid-dateA time without date in the same request, or a date that cannot be read.See Dates and scheduling.

Everything else — 401, 403, 429, 5xx — behaves as described in Errors.

What's next

Estimating and deleting

Price the draft again after an edit, or remove it.

Reading campaigns

Where the updatedAt every edit needs comes from.

Message content

The copy, senders, RCS content, fallback and languages an edit changes.

Last updated November 19, 2026

PreviousCreating a draftNextAudience targeting
  • Which campaigns can be edited
  • Read, change, write back
  • What each field does
  • The audience goes whole
  • The channel block merges key by key
  • The response
  • Errors
  • What's next

© 2026 Instasent

Privacy PolicyTerms & ConditionsCookie PolicyLegal Notice
All systems operational