Update draft

put/v1/drafts/{id}
Any API key or signed-in userAbout roles

No specific role is required; any valid credential works.

Updates a draft.

You can use this endpoint to update any available properties for a channel.

sendAt property options

  • If the sendAt property is set to a valid timestamp, the draft will be scheduled to be sent.
  • If the sendAt property is empty, the draft will be unscheduled.
  • If the sendAt property is omitted, the draft status won't change.
About this resource

Drafts

A draft is an outbound message that hasn't been sent yet. Unlike creating a message, sending a draft makes Kustomer deliver it to the customer through a connected channel such as email, SMS, chat or WhatsApp.

A draft is what an agent is composing in the reply box before they press send, and it's also how integrations send real messages. Creating a message only records something on the timeline; creating and sending a draft makes Kustomer deliver it through the channel and account you pick. Once a draft is sent, Kustomer removes it and records the delivered message as an out message on the conversation. Integrations use drafts to prepare replies for an agent to review, such as an AI-suggested answer, or to send notifications and follow-ups on a schedule.

Channels

Every draft is created for a customer and has a channel: email, sms, chat, whatsapp, facebook, instagram, twitter-dm, twitter-tweet or note. The channel decides which fields apply and the body limit, which ranges from 280 characters for a tweet to 10,240 for email, chat and notes. Email drafts take to, from, cc, bcc, subject and an optional template; app picks the sending integration, such as gmail or postmark for email or twilio for SMS. The sender (from) should be one of your org's connected accounts, which GET /v1/outboundAccounts lists for every channel. Pass conversation to reply in an existing conversation.

A note draft is an unsent internal note, and a conversation can have only one. Add createConversation=true when creating a note draft to open a new conversation for it.

Sending and scheduling

status Meaning
draft Saved, not sent.
scheduled Waiting for its sendAt time.
error Sending failed; see error.

sendAt controls sending. "sendAt": "now" sends the draft right away. To schedule it, send a future timestamp together with scheduled: true; scheduling works up to 30 days ahead. A future timestamp without scheduled: true is treated as now, so the draft goes out immediately. Leaving sendAt out keeps it a draft. On PUT /v1/drafts/{id}, an empty sendAt unschedules a scheduled draft and returns it to draft.

Scheduled drafts are locked. Editing one for any other reason, or deleting it, fails with 409 Conflict unless you pass force=true.

Which endpoint to use

To Call
Create a draft, or send a message right away POST /v1/customers/{id}/drafts
List a customer's unsent drafts GET /v1/customers/{id}/drafts
Edit, send, schedule or unschedule a draft PUT /v1/drafts/{id}
Discard a draft DELETE /v1/drafts/{id}
Find the accounts you can send from GET /v1/outboundAccounts
Read or edit a draft forward GET or PUT /v1/forwards/{id}

A client can create 120 drafts per customer per minute, including scheduled ones, and WhatsApp drafts have their own per-user limit (see Rate limits). WhatsApp media must be one of the supported file types listed on the create endpoint. DELETE with deleteConversation=true also removes the conversation, but only if it has no messages, notes or other drafts and was created by the same user. Files go on drafts through the draft attachment endpoints.

RelatedMessagesConversation forwardsDraft attachmentsConversations and messages

Path parameters

idstringrequired

Unique draft ID.

Example "5823e4d3bff98a100085320e"

Query parameters

forceboolean

Force the draft update or delete when supported by the draft service.

Example true

Request body

application/jsonrequired
One of
channelstringrequired
One of"email"
conversationstring<object-id>
appstring
One of"gmail""postmark"
customerstring<object-id>
autoboolean
scheduledboolean
sendAtstring<date-time-math>nullable
sourcestring
One of"bulk""satisfaction""biz-rules"
langstringlangnullable
max length 100
shortcutsarray<string<object-id>>
kbArticlesarray<string<object-id>>
oneOf
object
bodystring
max length 10240
htmlBodystring
max length 10240
array<object>
array<object>
subjectstring
min length 1
replyTostring<email-relaxed>
min length 3 · max length 256
array<object>
templateTypestringnullable
One of"email-reply""email-autoresponse""email-satisfaction"
templatestring<object-id>nullable
payloadobject

Responses

OK

objectrequired