Update a broadcast

Edit a draft broadcast before it goes out.

PATCH /v1/broadcasts/{id}

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

Path parameters

Parameter	Type	Required	Description
id	string	Yes	The broadcast id.

Body parameters

Every field is optional — send only what you want to change.

Parameter	Type	Description
from	string	The sender address. Max 320 characters.
subject	string	The subject line. Max 998 characters.
segment_id	string | null	Replaces the target segment. Pass null to target your whole audience.
topic_id	string | null	The topic to scope the send to, or null to clear it.
html	string | null	The HTML body. Contact properties render here — e.g. {{{contact.first_name}}}.
text	string | null	A plain-text part. If omitted, plain text is derived from the html at send time.
preview_text	string | null	Inbox preview text. Max 255 characters.
reply_to	string | null	A reply-to address. Max 320 characters.
name	string | null	A friendly name. Max 160 characters.

Example

curl

curl -X PATCH "https://api.sendgrail.com/v1/broadcasts/$BROADCAST_ID" \
  -H "Authorization: Bearer $SENDGRAIL_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "subject": "What shipped this month (updated)",
    "segment_id": "0a7d3c14-9b52-4e88-8f61-2d5a6c9b1e07"
  }'

Node.js

const res = await fetch(
  `https://api.sendgrail.com/v1/broadcasts/${id}`,
  {
    method: 'PATCH',
    headers: {
      Authorization: `Bearer ${process.env.SENDGRAIL_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      subject: 'What shipped this month (updated)',
      segment_id: '0a7d3c14-9b52-4e88-8f61-2d5a6c9b1e07',
    }),
  },
);

const broadcast = await res.json();

Passing segment_id replaces the target — the broadcast now goes to that segment, and only that segment.

Response

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

Only a draft can be edited

Update applies only to a broadcast still in draft. One that has been sent or scheduled answers 409 broadcast_not_editable:

{
  "message": "Only a draft broadcast can be edited.",
  "code": "broadcast_not_editable",
  "request_id": "8f2c1e64-1b17-4f8c-9f0e-3b6c1e0f5c31"
}

To edit a broadcast that is already scheduled, cancel the send first — deleting a scheduled broadcast cancels it in the dashboard — then recreate or re-edit the draft.

Unknown segment or topic

A segment_id or topic_id that doesn't belong to your team answers 404. See Errors for the full list of codes.