Create a draft email broadcast. html is the send-ready body. Optional internalTemplate is visual-editor source; if set it must be paired with html and cannot be added later. Set audience to either a Mongo-style user filter (sync users via Users API first; for large lists) or a raw email list (max 10,000). Include name, from fields, subject, and HTML. Notification type is optional on create and required before send or schedule; it is created automatically if missing.

POST

/broadcasts

curl --request POST \
  --url https://api.pingram.io/broadcasts \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "name": "example", "type": "example", "channel": "email", "audience": { "filter": { "additionalProperty": "example" }, "emails": [ "example" ] }, "fromName": "example", "fromAddress": "example", "replyToAddress": "example", "subject": "example", "html": "example", "internalTemplate": "example" }'

• Production

Authorizations

• apiKey
• clientCredentials
• endUser
• endUserHashed

Request Body^required

Media typeapplication/json

object

name

required

string

type

Notification type id. Optional on create; required before send/schedule. Created on the fly when missing.

string

channel

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

string

internalTemplate

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

string

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