Create a segment

Create a named list of contacts you can target with a broadcast.

POST /v1/segments

Requires a Full access API key — segments shape your audience, so a sending key embedded in an app cannot create them.

Body parameters

Parameter	Type	Required	Description
name	string	Yes	The segment name. Max 120 characters.
description	string | null	No	What this list is for. Max 255 characters.

Example

curl

curl -X POST 'https://api.sendgrail.com/v1/segments' \
  -H "Authorization: Bearer $SENDGRAIL_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Trial users",
    "description": "Signed up in the last 14 days and has not paid yet"
  }'

Node.js

const res = await fetch('https://api.sendgrail.com/v1/segments', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SENDGRAIL_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Trial users',
    description: 'Signed up in the last 14 days and has not paid yet',
  }),
});

const segment = await res.json();

Response

{
  "object": "segment",
  "id": "3f1c9a52-6d0e-4a1b-9a2f-7c4e1b0d8e33",
  "name": "Trial users",
  "description": "Signed up in the last 14 days and has not paid yet",
  "contacts_count": 0,
  "created_at": "2026-07-14T19:44:32+00:00"
}

A new segment is always empty, so contacts_count starts at 0.

Membership is managed from the contact

There is no "add contacts" parameter here, and no endpoint on the segment for putting people on it. You add a contact to a segment from the contact:

POST /v1/contacts/{id}/segments

That is the direction an integration actually works in — you have just seen a contact do something, and you know which list that puts them on. See Contact segments.

To read the other way round — who is on this list — use List segment contacts.