Update draft forward

put/v1/forwards/{id}

Any API key or signed-in userAbout roles

No specific role is required; any valid credential works.

Updates a draft forward.

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

Forward ID.

Example "60254e3ec413ae00571e3c99"

Query parameters

forceboolean

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

Example true

Request body

application/jsonrequired

## Request body details

| Name | Detail | | ------------- | ------------- | | body | The message body included with the forwarded conversation. | | from | The email address sending the forward. | | lang | Describes the language of the object's contents | | sendAt | A date in ISO format. Including this property will schedule the forward to be delivered. | | status | The status of the forward. A draft status indicates the forward is not scheduled for delivery and still editable. A scheduled status indicates the forward is scheduled for delivery by an email app (postmark or gmail). A draft will be update to a failed or sent status after a delivery attempt. | | subject | The subject of the forwarded conversation. | | template | The ID of a template that should be used for the forward. | | to | The destination email address of the forward. This an array that can accept more than one email recipient. | | attachments | The attachments to be sent along the forward. They must exist in S3

### sendAt property options * If you update the sendAt property to a valid timestamp, the forward will be scheduled to be sent and updated to a "scheduled" status. * If you ommit the sendAt property, the draft status will remain unchanged.

statusstring

One of"draft""sent""failed"

sendAtstring<date-time-math>

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

langstringlangnullable

max length 100

array<object>

object

bodystring

max length 10240

subjectstring

min length 1

replyTostring<email-relaxed>

min length 3 · max length 256

templatestring<object-id>nullable

payloadobject

array<object>

Responses

objectrequired

Open in the API console

curl --request PUT \
  --url 'https://api.kustomerapp.com/v1/forwards/60254e3ec413ae00571e3c99' \
  --header "Authorization: Bearer $KUSTOMER_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "status": "draft",
  "sendAt": "string",
  "lang": "string",
  "to": [
    {
      "email": "jane.doe@example.com",
      "name": "example_name"
    }
  ],
  "body": "Example text",
  "subject": "Example title"
}'

{
  "data": {
    "id": "5823e4d3bff98a100085320e",
    "type": "forward",
    "attributes": {
      "app": "gmail",
      "channel": "email",
      "body": "A great response",
      "status": "scheduled",
      "from": {
        "name": "Support",
        "email": "support@example.com"
      },
      "to": [
        {
          "name": "Billing",
          "email": "billing@email.com"
        }
      ],
      "sendAt": "2019-11-10T03:09:07.575Z",
      "createdAt": "2016-11-10T03:09:07.575Z",
      "updatedAt": "2016-11-10T03:16:55.464Z",
      "modifiedAt": "2016-11-10T03:16:55.464Z"
    },
    "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"
        }
      },
      "attachments": {
        "data": [
          {
            "type": "attachment",
            "id": "58c766aadd4b90110053bd81"
          }
        ],
        "links": [
          {
            "self": "/v1/forwards/5823e4d3bff98a100085320e/attachments"
          }
        ]
      }
    }
  }
}