Skip to content

Retrieve a broadcast ​

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

http
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 ​

ParameterTypeRequiredDescription
idstringYesThe broadcast id.

Example ​

bash
curl "https://api.sendgrail.com/v1/broadcasts/$BROADCAST_ID" \
  -H "Authorization: Bearer $SENDGRAIL_API_KEY"
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 ​

json
{
  "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 ​

StatusMeaning
draftCreated, not yet sent.
scheduledQueued to send at scheduled_at.
queuedSending now — handed to the delivery queue.
sentDelivered to the queue for every recipient.
cancelledThe scheduled send was cancelled.
failedThe 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.

json
{
  "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.

Transactional email on your own domain.