List broadcasts

Every broadcast on your team, newest first.

GET /v1/broadcasts

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

Query parameters

Cursor-paginated:

Parameter	Type	Description
limit	number	How many to return. Default 20, min 1, max 100.
after	string	Return broadcasts after this id. Cannot be combined with before.
before	string	Return broadcasts before this id. Cannot be combined with after.

Example

curl

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

Node.js

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

const { data, has_more } = await res.json();

Response

{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "id": "e4f9a2c1-7b83-4d6e-9a1f-2c5b8e0d3a47",
      "name": "July product update",
      "segment_id": "3f1c9a52-6d0e-4a1b-9a2f-7c4e1b0d8e33",
      "status": "sent",
      "created_at": "2026-07-14T19:44:32+00:00",
      "scheduled_at": null,
      "sent_at": "2026-07-14T19:45:10+00:00"
    },
    {
      "id": "0a7d3c14-9b52-4e88-8f61-2d5a6c9b1e07",
      "name": "Untitled broadcast",
      "segment_id": null,
      "status": "draft",
      "created_at": "2026-07-13T09:12:04+00:00",
      "scheduled_at": null,
      "sent_at": null
    }
  ]
}

The list rows are lean — no from, subject, html or text. A page of full bodies would be weight you didn't ask for. Fetch one broadcast with Retrieve a broadcast to see its body.

has_more tells you whether another page exists — there is no total, because a keyset paginator never counts the table. To walk every page, pass the last id you saw as after until has_more is false. See Pagination.