Skip to content
Optiwork API Docs

Schedule a draft for later

POST
/mail/mailboxes/{mailbox}/scheduled
curl --request POST \
  --url https://mail.work.optidata.cloud/api/mail/mailboxes/78/scheduled \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "draft_id": 918, "scheduled_at": "2026-08-20 09:00:00", "timezone": "America/Sao_Paulo" }'

Hand a saved draft a delivery time. The moment is read in the timezone you send and must be at least 10 minutes in the future.

Requires scheduled sending to be enabled for the tenant.

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
object
draft_id
required

Id of the draft to deliver.

integer
scheduled_at
required

When to deliver it, read in timezone.

string
timezone
required

IANA time zone the moment is expressed in.

string
Examples
ExampletomorrowMorning
{
  "draft_id": 918,
  "scheduled_at": "2026-08-20 09:00:00",
  "timezone": "America/Sao_Paulo"
}

Responses

Section titled “ Responses ”

201

Section titled “201”

The delivery was scheduled.

Media typeapplication/json

A draft waiting for its delivery time.

object
id
integer
draft_id
integer
mailbox_id
integer
scheduled_at

When the message will be sent.

string
timezone

The time zone the user chose the moment in.

string
status

Where a scheduled delivery stands.

string
Allowed values: pending processing sent failed cancelled
sent_at
string | null
attempts

How many delivery attempts have been made.

integer
last_error

Why the last attempt failed, when one did.

string | null
created_at
string
updated_at
string
Example
{
  "id": 44,
  "timezone": "America/Sao_Paulo",
  "status": "pending"
}

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”

Scheduled sending is not enabled for this tenant.

Media typeapplication/json

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

object
message
required

Human-readable description of the failure.

string
Examples
Exampledisabled
{
  "message": "Not available"
}

422

Section titled “422”

The draft does not exist, or the moment is missing, unparseable or less than 10 minutes away.

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
ExampletooSoon
{
  "message": "The scheduled time must be at least 10 minutes from now.",
  "errors": {
    "scheduled_at": [
      "The scheduled time must be at least 10 minutes from now."
    ]
  }
}

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."
}