Create draft for customer

post/v1/customers/{id}/drafts

Any API key or signed-in userAbout roles

No specific role is required; any valid credential works.

Creates an outbound draft to a customer through a specific channel (email, SMS, Facebook DM, etc).

Scheduling drafts

To schedule a draft to be sent at a future time, you must include both:

A sendAt timestamp that is in the future
"scheduled": true in the request body

If scheduled is omitted, the system will override your sendAt value and create the draft immediately.

Note drafts

You can also create note drafts by specifying the channel as note in the request body channel field. You can have one note draft per conversation.

Rate limit

Customer drafts are subject to a rate limit. A single client can create up to 120 drafts per minute per customer, including drafts scheduled for the future. A 429 Too Many Requests response will be returned if the rate limit has been reached for a customer.

WhatsApp outbound messages are limited to 400 messages per minute per user. This limit applies to both machine and non-machine (human) users.

WhatsApp media file support

When creating a WhatsApp draft that includes media, only specific file types are supported. Unsupported media types (e.g. .videomp4) will be blocked before submission to prevent send failures.

Supported file types for WhatsApp messages are:

AUDIO: aac, mp4, amr, mpeg, mp3, ogg, m4a
VIDEO: mp4, 3gp, 3gpp
DOCUMENT: txt, pdf, doc, docx, xls, xlsx, ppt, pptx
IMAGE: jpeg, jpg, png
STICKER: webp

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.

Path parameters

idstringrequired

Customer ID.

Example "5f8efdd5d3de932f344ca367"

Query parameters

createConversationboolean

Create a conversation while creating the customer draft.

Example false

Request body

application/jsonrequired

One of

channelstringrequired

The communication channel for the message.

One of"email"

conversationstring<object-id>

appstring

One of"gmail""postmark"

customerstring<object-id>

autoboolean

If true, message was automatically generated from a Kustomer workflow or auto-response feature. If set to true, this message will be excluded from reporting metrics. If false, message was created by a manual method.

sendAtstring<date-time-math>nullable

A timestamp for a future date/time the drafted message to be sent at.

scheduledboolean

Indicates that the draft should be scheduled for future delivery. Required when using a future sendAt timestamp.

sourcestring

One of"bulk""satisfaction"

langstringlangnullable

max length 100

shortcutsarray<string<object-id>>

The ID string associated with a shortcut. Shortcuts are pre-defined blocks of text defined in Kustomer. See Get All Shortcuts endpoint view currently available shortcuts or create a shortcut with the Create Shortcut endpoint. to Learn more about shortcuts in the Use workspace shortcuts article.

kbArticlesarray<string<object-id>>

oneOf

object

bodystring

max length 10240

array<object>

subjectstring

min length 1

replyTostring<email-relaxed>

min length 3 · max length 256

array<object>

templatestring<object-id>nullable

payloadobject

Responses

objectrequired

Open in the API console

curl --request POST \
  --url 'https://api.kustomerapp.com/v1/customers/5f8efdd5d3de932f344ca367/drafts' \
  --header "Authorization: Bearer $KUSTOMER_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "channel": "email",
  "app": "gmail",
  "body": "Example text"
}'

{
  "data": {
    "id": "5823e4d3bff98a100085320e",
    "type": "draft",
    "attributes": {
      "channel": "email",
      "status": "draft",
      "createdAt": "2016-11-10T03:09:07.575Z",
      "updatedAt": "2016-11-10T03:09:07.575Z",
      "modifiedAt": "2016-11-10T03:09:07.575Z"
    },
    "relationships": {
      "org": {
        "data": {
          "type": "org",
          "id": "57f29863a1dbf61100e6aa92"
        },
        "links": {
          "self": "/v1/orgs/57f29863a1dbf61100e6aa92"
        }
      },
      "customer": {
        "data": {
          "type": "customer",
          "id": "58210c3db0f09110006b7953"
        },
        "links": {
          "self": "/v1/customers/58210c3db0f09110006b7953"
        }
      },
      "createdBy": {
        "data": {
          "type": "user",
          "id": "58190b991f2932100010d683"
        },
        "links": {
          "self": "/v1/users/58190b991f2932100010d683"
        }
      },
      "modifiedBy": {
        "data": {
          "type": "user",
          "id": "58190b991f2932100010d683"
        },
        "links": {
          "self": "/v1/users/58190b991f2932100010d683"
        }
      }
    }
  }
}