Skip to content
Optiwork API Docs

Create or update a draft

POST
/mail/mailboxes/{mailbox}/drafts/save
curl --request POST \
  --url https://mail.work.optidata.cloud/api/mail/mailboxes/78/drafts/save \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "draft_id": "918", "to": [ "john.roe@example.com" ], "cc": [], "bcc": [], "subject": "Quarterly report", "body": "<p>Hi John, the report is attached.</p>", "type": "new", "is_read_receipt_enabled": false }'

Save the current state of a composition. Omit draft_id to create a new draft; send it to update the one you already have — this is the call an autosave loop makes.

Set reply_server_message_id when the composition answers an existing message, and type to say how (new, reply or forward). The returned draft’s id is the draft_id you later hand to a send operation.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “ Parameters ”

Path Parameters

Section titled “Path Parameters”
mailbox
required
integer

Id of the mailbox. Every mailbox the caller may use is listed in their account.

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json

The state of a composition to save.

object
draft_id

Id of the draft to update. Omit to create a new one.

string | null
reply_server_message_id

Id of the message being answered, for a reply or a forward.

string | null
to

Recipient addresses.

Array<string> | null
cc
Array<string> | null
bcc
Array<string> | null
subject
string | null
<= 255 characters
body

HTML body.

string | null
type
One of:

How an outgoing message came to be.

string
Allowed values: new reply forward
attachments

Files carried by the draft.

Array<object> | null
object
is_read_receipt_enabled

Ask the recipient’s client for a read receipt.

boolean | null
Examples
Exampleautosave
{
  "draft_id": "918",
  "to": [
    "john.roe@example.com"
  ],
  "cc": [],
  "bcc": [],
  "subject": "Quarterly report",
  "body": "<p>Hi John, the report is attached.</p>",
  "type": "new",
  "is_read_receipt_enabled": false
}

Responses

Section titled “ Responses ”

200

Section titled “200”

The saved draft.

Media typeapplication/json
object
message
string
draft

A message being composed.

object
id
integer
mailbox_id
integer
type

How an outgoing message came to be.

string
Allowed values: new reply forward
status

Where a draft stands. not_sent is still being written, sending has been handed to the queue, sent has left, and failed could not be delivered.

string
Allowed values: not_sent sending sent failed
reply_server_message_id

The message this draft answers, when it answers one.

string | null
subject
string | null
body
string | null
date
string
is_read_receipt_enabled
boolean
from
Array<object>

One participant of a message.

object
name

Display name, when one is known.

string | null
email
string format: email
type

The role the address plays: f sender, t recipient, c carbon copy, b blind copy, r reply-to.

string | null
to
Array<object> | null

One participant of a message.

object
name

Display name, when one is known.

string | null
email
string format: email
type

The role the address plays: f sender, t recipient, c carbon copy, b blind copy, r reply-to.

string | null
cc
Array<object> | null

One participant of a message.

object
name

Display name, when one is known.

string | null
email
string format: email
type

The role the address plays: f sender, t recipient, c carbon copy, b blind copy, r reply-to.

string | null
bcc
Array<object> | null

One participant of a message.

object
name

Display name, when one is known.

string | null
email
string format: email
type

The role the address plays: f sender, t recipient, c carbon copy, b blind copy, r reply-to.

string | null
attachments

The files uploaded to the draft.

Array<object>
object
created_at
string
updated_at
string
mailbox

A mailbox the user has access to.

object
id
integer
user_id
integer
cuid

Cross-application user id the mailbox belongs to.

string
email
string format: email
created_at
string
updated_at
string
deleted_at
string | null
should_change_password
boolean
Example
{
  "message": "Draft saved successfully.",
  "draft": {
    "id": 918,
    "type": "new",
    "status": "not_sent",
    "from": [
      {
        "name": "Jane Doe",
        "email": "jane.doe@acme.example",
        "type": "f"
      }
    ],
    "to": [
      {
        "name": "Jane Doe",
        "email": "jane.doe@acme.example",
        "type": "f"
      }
    ],
    "cc": [
      {
        "name": "Jane Doe",
        "email": "jane.doe@acme.example",
        "type": "f"
      }
    ],
    "bcc": [
      {
        "name": "Jane Doe",
        "email": "jane.doe@acme.example",
        "type": "f"
      }
    ]
  },
  "mailbox": {
    "id": 78
  }
}

401

Section titled “401”

Missing, malformed or expired authentication key.

Media typeapplication/json

Authentication failures use an error key rather than message.

object
error
required
string
Examples
Examplemissing

No bearer token sent

{
  "error": "JWT passport exception: Missing bearer token in request"
}

403

Section titled “403”

The caller may not act on this mailbox, user or resource.

Media typeapplication/json

Generic error envelope used by policy, binding and framework failures.

object
message
required

Human-readable description of the failure.

string
Examples
Exampledenied
{
  "message": "This action is unauthorized."
}

422

Section titled “422”

The request body or query string failed validation.

Media typeapplication/json
object
message
required

The first validation message.

string
errors
required

Validation messages keyed by field name.

object
key
additional properties
Array<string>
Examples
Exampleinvalid
{
  "message": "The conversations field is required.",
  "errors": {
    "conversation_ids": [
      "The conversations field is required."
    ]
  }
}

429

Section titled “429”

Rate limit exceeded. Retry after the window resets.

Media typeapplication/json

Generic error envelope used by policy, binding and framework failures.

object
message
required

Human-readable description of the failure.

string
Examples
Examplethrottled
{
  "message": "Too Many Attempts."
}