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

GET /v1/contacts/{id}/segments

Path parameters

Parameter	Type	Required	Description
id	string	Yes	The contact id, or the contact's email address.

Query parameters

Cursor-paginated:

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

Example

curl

curl "https://api.sendgrail.com/v1/contacts/ada@example.com/segments" \
  -H "Authorization: Bearer $SENDGRAIL_API_KEY"

Node.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

{
  "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

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

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

Path parameters

Parameter	Type	Required	Description
id	string	Yes	The contact id, or the contact's email address.
segment_id	string	Yes	The id of the segment to add the contact to. Must be a segment on your team.

Example

curl

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

Node.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:

{
  "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:

{
  "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

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

Path parameters

Parameter	Type	Required	Description
id	string	Yes	The contact id, or the contact's email address.
segment_id	string	Yes	The id of the segment to remove the contact from.

Example

curl

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

Node.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

{
  "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.