Skip to content

Contact segments ​

A segment is a named list of contacts. Membership is managed from the contact's side: you list, add and remove a contact's segments here.

All three endpoints require a Full access API key, and all three accept the contact's id or its email address in the path.

List a contact's segments ​

http
GET /v1/contacts/{id}/segments

Path parameters ​

ParameterTypeRequiredDescription
idstringYesThe contact id, or the contact's email address.

Query parameters ​

Cursor-paginated:

ParameterTypeRequiredDescription
limitnumberNoHow many to return. Default 20, min 1, max 100.
afterstringNoReturn segments after this segment id. Cannot be combined with before.
beforestringNoReturn segments before this segment id. Cannot be combined with after.

Example ​

bash
curl "https://api.sendgrail.com/v1/contacts/ada@example.com/segments" \
  -H "Authorization: Bearer $SENDGRAIL_API_KEY"
js
const res = await fetch(
  `https://api.sendgrail.com/v1/contacts/${encodeURIComponent('ada@example.com')}/segments`,
  { headers: { Authorization: `Bearer ${process.env.SENDGRAIL_API_KEY}` } },
);

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

Response ​

json
{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "object": "segment",
      "id": "7a2b6f10-5c94-4f7d-9a3e-8c1b0d6e2f45",
      "name": "Trial users"
    }
  ]
}

Only the segments this contact belongs to, newest first. A contact in no segments returns an empty data array, not a 404.

Add a contact to a segment ​

http
POST /v1/contacts/{id}/segments/{segment_id}

The segment goes in the path — there is no request body.

Path parameters ​

ParameterTypeRequiredDescription
idstringYesThe contact id, or the contact's email address.
segment_idstringYesThe id of the segment to add the contact to. Must be a segment on your team.

Example ​

bash
curl -X POST "https://api.sendgrail.com/v1/contacts/ada@example.com/segments/7a2b6f10-5c94-4f7d-9a3e-8c1b0d6e2f45" \
  -H "Authorization: Bearer $SENDGRAIL_API_KEY"
js
const segmentId = '7a2b6f10-5c94-4f7d-9a3e-8c1b0d6e2f45';

const res = await fetch(
  `https://api.sendgrail.com/v1/contacts/${encodeURIComponent('ada@example.com')}/segments/${segmentId}`,
  {
    method: 'POST',
    headers: { Authorization: `Bearer ${process.env.SENDGRAIL_API_KEY}` },
  },
);

const segment = await res.json();

Response ​

201 Created, with the segment the contact was added to:

json
{
  "object": "segment",
  "id": "7a2b6f10-5c94-4f7d-9a3e-8c1b0d6e2f45",
  "name": "Trial users"
}

Adding a contact who is already in the segment is not an error — you get the same 201 and the membership is unchanged. Membership is a set, not a log, so "add" means "make sure they're in it". That lets you replay a webhook or retry a failed request without first checking whether it already landed.

A segment_id that isn't one of your team's segments is a 404:

json
{
  "message": "No segment with the id 7a2b6f10-5c94-4f7d-9a3e-8c1b0d6e2f45.",
  "code": "not_found",
  "request_id": "8f2c1e64-1b17-4f8c-9f0e-3b6c1e0f5c31"
}

Remove a contact from a segment ​

http
DELETE /v1/contacts/{id}/segments/{segment_id}

Path parameters ​

ParameterTypeRequiredDescription
idstringYesThe contact id, or the contact's email address.
segment_idstringYesThe id of the segment to remove the contact from.

Example ​

bash
curl -X DELETE "https://api.sendgrail.com/v1/contacts/ada@example.com/segments/$SEGMENT_ID" \
  -H "Authorization: Bearer $SENDGRAIL_API_KEY"
js
await fetch(
  `https://api.sendgrail.com/v1/contacts/${encodeURIComponent('ada@example.com')}/segments/${segmentId}`,
  {
    method: 'DELETE',
    headers: { Authorization: `Bearer ${process.env.SENDGRAIL_API_KEY}` },
  },
);

Response ​

json
{
  "object": "segment",
  "id": "7a2b6f10-5c94-4f7d-9a3e-8c1b0d6e2f45",
  "deleted": true
}

deleted here refers to the membership, not the segment: the segment still exists and the contact still exists. Removing a contact who wasn't in the segment is likewise not an error.

To delete the contact itself, see Delete a contact.

Transactional email on your own domain.