Schedule a draft email broadcast for a future ISO datetime (sendAt). Requires a non-empty subject. fromAddress must be the platform default sender or a domain verified for this account (Settings → Domain Verification). The platform default sender is for testing only (at most 10 recipients, heavily throttled). Cancels any existing schedule when the broadcast is returned to draft via cancel.

POST

/broadcasts/{broadcastId}/schedule

curl --request POST \
  --url https://api.pingram.io/broadcasts/example/schedule \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "sendAt": "example" }'

• Production

Authorizations

• apiKey
• clientCredentials
• endUser
• endUserHashed

Parameters

Path Parameters

broadcastId

required

string

Broadcast ID

Request Body^required

Media typeapplication/json

object

sendAt

required

ISO datetime in the future.

string

Example^generated

{
  "sendAt": "example"
}

Responses

200

Successful response

Media typeapplication/json

Broadcast as returned by the API (html + optional internalTemplate on single-get only).

object

broadcastId

required

UUIDv7 (time-ordered).

string

name

required

string

status

required

Lifecycle status of an email broadcast.

string

Allowed values: draft scheduled sending sent paused canceled

pausedReason

string

Allowed values: PAUSED_BY_USER REPUTATION_GUARD PLAN_EXCEEDED PENDING_VERIFICATION AUDIENCE_LIMITS_EXCEEDED UNVERIFIED_DOMAIN SPAM_CONTENT

type

Notification type id. Required before send or schedule.

string

channel

required

Email-only in v1; forward-compatible field.

string

Allowed values: email

audience

required

Broadcast audience: exactly one of filter (Mongo-style query evaluated against synced user objects) or emails (raw list, max 10,000 addresses; for larger audiences use filter after syncing users via the Users API).

object

filter

object

key

additional properties

emails

Array<string>

fromName

required

string

fromAddress

required

string

replyToAddress

string

subject

required

string

html

required

Send-ready HTML body.

string

internalTemplate

Optional visual-editor source. Can only be set at create time and must stay paired with html.

string

scheduleAt

ISO datetime for scheduled broadcasts.

string

archivedAt

Set when the user archives the broadcast; hidden from the default list.

string

createdAt

required

string

updatedAt

required

string

Example

{
  "status": "draft",
  "pausedReason": "PAUSED_BY_USER",
  "channel": "email"
}

400

Bad Request - validation errors, invalid input

Media typeapplication/json

Standard error response for API errors.

object

trackingId

required

Unique tracking ID for the request.

string

error

required

Structured error details for API error responses.

object

code

required

Machine-readable error code.

string

message

required

Human-readable error message.

string

fix

Actionable hint for fixing the error.

string

Example^generated

{
  "trackingId": "example",
  "error": {
    "code": "example",
    "message": "example",
    "fix": "example"
  }
}

401

Unauthorized

402

Payment Required - usage limits exceeded

Media typeapplication/json

Standard error response for API errors.

object

trackingId

required

Unique tracking ID for the request.

string

error

required

Structured error details for API error responses.

object

code

required

Machine-readable error code.

string

message

required

Human-readable error message.

string

fix

Actionable hint for fixing the error.

string

Example^generated

{
  "trackingId": "example",
  "error": {
    "code": "example",
    "message": "example",
    "fix": "example"
  }
}

500

Internal Server Error

502

Bad Gateway - provider error

Media typeapplication/json

Standard error response for API errors.

object

trackingId

required

Unique tracking ID for the request.

string

error

required

Structured error details for API error responses.

object

code

required

Machine-readable error code.

string

message

required

Human-readable error message.

string

fix

Actionable hint for fixing the error.

string

Example^generated

{
  "trackingId": "example",
  "error": {
    "code": "example",
    "message": "example",
    "fix": "example"
  }
}