Delete a segment

Remove a segment. The contacts on it are not touched.

DELETE /v1/segments/{id}

Requires a Full access API key.

Path parameters

Parameter	Type	Required	Description
id	string	Yes	The segment id.

Example

curl

curl -X DELETE "https://api.sendgrail.com/v1/segments/$SEGMENT_ID" \
  -H "Authorization: Bearer $SENDGRAIL_API_KEY"

Node.js

await fetch(`https://api.sendgrail.com/v1/segments/${id}`, {
  method: 'DELETE',
  headers: { Authorization: `Bearer ${process.env.SENDGRAIL_API_KEY}` },
});

Response

{
  "object": "segment",
  "id": "3f1c9a52-6d0e-4a1b-9a2f-7c4e1b0d8e33",
  "deleted": true
}

A scheduled broadcast blocks the delete

If a broadcast is scheduled or already sending to this segment, the delete is refused with 409:

{
  "message": "A scheduled or sending broadcast targets this segment. Cancel it first.",
  "code": "segment_in_use",
  "request_id": "8f2c1e64-1b17-4f8c-9f0e-3b6c1e0f5c31"
}

Allowing it would silently shrink that broadcast's audience — to nobody, if this was its only segment — and the send would go out, or not, with no one having decided that. Cancel the broadcast first, or leave the segment alone until it has gone out.

This deletes the list, not the people on it

Say it plainly, because it is the thing everyone fears: deleting a segment deletes the list, and nothing else. Every contact that was on it still exists, still has its properties, still has its subscription state, and still appears in your audience and in your other segments. All that is gone is the grouping.

What you do lose is the membership itself. Re-creating a segment with the same name gives you a new, empty list — the 128 contacts that used to be on the old one are not restored, because the rows that said so were deleted with it. If you may want the grouping back, keep the segment and stop targeting it.

Deleting a segment does not delete broadcasts that were sent to it, and does not unsubscribe anyone. To actually remove people from your audience, see Suppressions and Audiences.