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.
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.
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 is | What the edit does |
|---|---|
draft, preview, estimated, quoted | Applies. A quoted campaign loses its quote along with the estimate. |
estimating, quoting, preparing, unpreparing, continuing, resuming | 409 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 status | 409. 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 one | 409, 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:
Read the campaign
GET /campaign/{id}and keep itsupdatedAt.Send only what changes
expectedUpdatedAtset to that value, plus at least one field to change.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.
expectedUpdatedAtstringrequiredThe updatedAt of the campaign as you last read it.
title, emoji, descriptionstringEach one replaced when sent.
datestring | nullMoves 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.
audienceobjectReplaced whole. See The audience goes whole.
message, sender, fallback, compliance, translateToThe channel block, merged key by key into the campaign's current channel. See The channel block merges key by key.
channelstringAccepted 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.
messageobjectSend 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.
senderstringThe new sender. A translation that used the old sender follows it; one that has its own sender keeps it.
fallbackobjectRCS 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.
compliancestringbasic, 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.
translateToarrayThe 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.
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
| Status | When |
|---|---|
400 | The body is not a JSON object, expectedUpdatedAt is missing or not a date, or there is no field to change. |
404 | No campaign with that id. |
409 | The 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. |
422 | The 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:
errorCode | What happened | What to do |
|---|---|---|
channel-not-editable | channel names a different channel from the campaign's. | Drop channel, or create a new campaign on the other channel. |
unknown-segment | audience is not an object, or it has no include. | Send the whole audience: include (["_all"] for everyone) and exclude. |
fallback-not-supported | The 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-message | A 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-date | A 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
Last updated