Retrieve a broadcast

Fetch one broadcast by its id, with its full body.

GET /v1/broadcasts/{id}

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

Path parameters

Parameter	Type	Required	Description
id	string	Yes	The broadcast id.

Example

curl

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

Node.js

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

const broadcast = await res.json();

Response

{
  "object": "broadcast",
  "id": "e4f9a2c1-7b83-4d6e-9a1f-2c5b8e0d3a47",
  "name": "July product update",
  "segment_id": "3f1c9a52-6d0e-4a1b-9a2f-7c4e1b0d8e33",
  "topic_id": null,
  "from": "News <news@yourdomain.com>",
  "subject": "What shipped this month",
  "reply_to": null,
  "preview_text": "The month in one email",
  "html": "<p>Hi {{{contact.first_name}}}, here is what is new.</p>",
  "text": null,
  "status": "sent",
  "created_at": "2026-07-14T19:44:32+00:00",
  "scheduled_at": null,
  "sent_at": "2026-07-14T19:45:10+00:00"
}

segment_id is null when the broadcast targets your whole audience. text is null when you never supplied a plain-text part — one is derived from the html at send time.

Any broadcast on your team is retrievable this way, whether you created it through the API or in the dashboard.

Status

Status	Meaning
draft	Created, not yet sent.
scheduled	Queued to send at scheduled_at.
queued	Sending now — handed to the delivery queue.
sent	Delivered to the queue for every recipient.
cancelled	The scheduled send was cancelled.
failed	The send could not be completed.

Another team's broadcast

A broadcast belonging to another team answers 404, not 403 — an id that isn't yours is an id that doesn't exist, as far as your key is concerned.

{
  "message": "No broadcast with the id e4f9a2c1-7b83-4d6e-9a1f-2c5b8e0d3a47.",
  "code": "not_found",
  "request_id": "8f2c1e64-1b17-4f8c-9f0e-3b6c1e0f5c31"
}

See Errors for the full list of codes.