Send a broadcast

Send a draft broadcast now, or schedule it for later.

POST /v1/broadcasts/{id}/send

Requires a Full access API key — a broadcast reaches your audience, so a sending key embedded in an app cannot fire one.

Path parameters

Parameter	Type	Required	Description
id	string	Yes	The broadcast id.

Body parameters

Parameter	Type	Required	Description
scheduled_at	string | null	No	When to send. Omit to send now — see Scheduling.

Examples

Send now — no body needed:

curl

curl -X POST "https://api.sendgrail.com/v1/broadcasts/$BROADCAST_ID/send" \
  -H "Authorization: Bearer $SENDGRAIL_API_KEY"

Node.js

const res = await fetch(
  `https://api.sendgrail.com/v1/broadcasts/${id}/send`,
  {
    method: 'POST',
    headers: { Authorization: `Bearer ${process.env.SENDGRAIL_API_KEY}` },
  },
);

const broadcast = await res.json();

Schedule it instead by passing scheduled_at:

curl -X POST "https://api.sendgrail.com/v1/broadcasts/$BROADCAST_ID/send" \
  -H "Authorization: Bearer $SENDGRAIL_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{ "scheduled_at": "in 1 min" }'

Response

{
  "id": "e4f9a2c1-7b83-4d6e-9a1f-2c5b8e0d3a47"
}

Scheduling

scheduled_at accepts either natural language — "in 1 min", "tomorrow 9am" — or an ISO 8601 timestamp like "2026-08-05T11:52:01Z".

• Omit it and the broadcast sends now.
• It must be within 30 days. Further out is a 422 validation_error.
• A time under ~30 seconds away sends immediately rather than scheduling.

Only a draft can be sent

Send applies only to a broadcast still in draft. One that has already been sent or scheduled answers 409 broadcast_not_sendable:

{
  "message": "This broadcast has already been sent or scheduled.",
  "code": "broadcast_not_sendable",
  "request_id": "8f2c1e64-1b17-4f8c-9f0e-3b6c1e0f5c31"
}

To reschedule a broadcast that is already scheduled, cancel it first — deleting a scheduled broadcast cancels the send. See Delete a broadcast and Errors.