Segments API

8 operations. Guide: Manage contacts and consent. Requests and responses are JSON with snake_case fields; authenticate with Authorization: Bearer <api key>. The examples assume a client built as in SDKs and the command line.

Create a segment

POST /v1/segments

static segments hold members you add; dynamic ones match their rules whenever they are read.

Operation createSegment, SDK minket.segments.create. Keys: full access. Live keys only: test keys get 403 test_mode_only.

Request body

Field	Type	Required	Description
`name`	string	yes	1 to 100 characters.
`kind`	one of "static", "dynamic"	no	Default `"static"`.
`rules`	object	no
`rules (shape 1).all`	array of object	yes	At most 50 items.
`rules (shape 1).all[].field`	string	yes	At most 120 characters.
`rules (shape 1).all[].op`	one of "eq", "neq", "contains", "not_contains", "starts_with", "ends_with", "gt", "gte", "lt", "lte", "is_set", "is_not_set", …	yes
`rules (shape 1).all[].value`	string or number or boolean or array of string or null	no
`rules (shape 2).any`	array of object	yes	At most 50 items.
`rules (shape 2).any[].field`	string	yes	At most 120 characters.
`rules (shape 2).any[].op`	one of "eq", "neq", "contains", "not_contains", "starts_with", "ends_with", "gt", "gte", "lt", "lte", "is_set", "is_not_set", …	yes
`rules (shape 2).any[].value`	string or number or boolean or array of string or null	no

Response

201 Created: Segment.

Field	Type	Required	Description
`id`	string	yes	A UUID.
`object`	"segment"	yes
`project_id`	string	yes	A UUID.
`name`	string	yes
`kind`	one of "static", "dynamic"	yes
`rules`	object or null	yes
`rules (shape 1).all`	array of object	yes	At most 50 items.
`rules (shape 1).all[].field`	string	yes	At most 120 characters.
`rules (shape 1).all[].op`	one of "eq", "neq", "contains", "not_contains", "starts_with", "ends_with", "gt", "gte", "lt", "lte", "is_set", "is_not_set", …	yes
`rules (shape 1).all[].value`	string or number or boolean or array of string or null	no
`rules (shape 2).any`	array of object	yes	At most 50 items.
`rules (shape 2).any[].field`	string	yes	At most 120 characters.
`rules (shape 2).any[].op`	one of "eq", "neq", "contains", "not_contains", "starts_with", "ends_with", "gt", "gte", "lt", "lte", "is_set", "is_not_set", …	yes
`rules (shape 2).any[].value`	string or number or boolean or array of string or null	no
`contacts_count`	integer or null	yes
`created_at`	string (date-time)	yes	An ISO 8601 timestamp with timezone, for example 2026-10-24T18:00:00.000Z.
`updated_at`	string (date-time)	yes	An ISO 8601 timestamp with timezone, for example 2026-10-24T18:00:00.000Z.

Errors: 400, 401, 403, 404, 409, 422, 429, 500, with the error body.

Examples

curl

curl -X POST https://api.minket.com/v1/segments \
  -H "Authorization: Bearer $MINKET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Customers"}'

TypeScript

const result = await minket.segments.create({
  name: "Customers"
});

CLI

minket api createSegment --body '{"name":"Customers"}'

Python

from minket.api.segments import create_segment
from minket.models import CreateSegmentBody

result = create_segment.sync(client=client, body=CreateSegmentBody.from_dict({"name":"Customers"}))

var body minket.CreateSegmentJSONRequestBody
res, err := client.CreateSegmentWithResponse(ctx, body)

List segments

GET /v1/segments

Operation listSegments, SDK minket.segments.list. Keys: full access. Test keys work on test-mode data.

Parameters

Name	In	Type	Required	Description
`limit`	query	integer	no	Default `20`.
`after`	query	string	no	A UUID.
`before`	query	string	no	A UUID.

Response

200 Success: object.

Field	Type	Required	Description
`object`	"list"	yes
`data`	array of Segment	yes
`data[].id`	string	yes	A UUID.
`data[].object`	"segment"	yes
`data[].project_id`	string	yes	A UUID.
`data[].name`	string	yes
`data[].kind`	one of "static", "dynamic"	yes
`data[].rules`	object or null	yes
`data[].rules (shape 1).all`	array of object	yes	At most 50 items.
`data[].rules (shape 1).all[].field`	string	yes	At most 120 characters.
`data[].rules (shape 1).all[].op`	one of "eq", "neq", "contains", "not_contains", "starts_with", "ends_with", "gt", "gte", "lt", "lte", "is_set", "is_not_set", …	yes
`data[].rules (shape 1).all[].value`	string or number or boolean or array of string or null	no
`data[].rules (shape 2).any`	array of object	yes	At most 50 items.
`data[].rules (shape 2).any[].field`	string	yes	At most 120 characters.
`data[].rules (shape 2).any[].op`	one of "eq", "neq", "contains", "not_contains", "starts_with", "ends_with", "gt", "gte", "lt", "lte", "is_set", "is_not_set", …	yes
`data[].rules (shape 2).any[].value`	string or number or boolean or array of string or null	no
`data[].contacts_count`	integer or null	yes
`data[].created_at`	string (date-time)	yes	An ISO 8601 timestamp with timezone, for example 2026-10-24T18:00:00.000Z.
`data[].updated_at`	string (date-time)	yes	An ISO 8601 timestamp with timezone, for example 2026-10-24T18:00:00.000Z.
`has_more`	boolean	yes

Errors: 400, 401, 403, 404, 409, 422, 429, 500, with the error body.

Examples

curl

curl https://api.minket.com/v1/segments \
  -H "Authorization: Bearer $MINKET_API_KEY"

TypeScript

const result = await minket.segments.list();

CLI

minket api listSegments

Python

from minket.api.segments import list_segments

result = list_segments.sync(client=client)

res, err := client.ListSegmentsWithResponse(ctx, &minket.ListSegmentsParams{})

Get a segment

GET /v1/segments/{id}

Operation getSegment, SDK minket.segments.get. Keys: full access. Test keys work on test-mode data.

Parameters

Name	In	Type	Required	Description
`id`	path	string	yes	A UUID.

Response

200 Success: Segment.

Field	Type	Required	Description
`id`	string	yes	A UUID.
`object`	"segment"	yes
`project_id`	string	yes	A UUID.
`name`	string	yes
`kind`	one of "static", "dynamic"	yes
`rules`	object or null	yes
`rules (shape 1).all`	array of object	yes	At most 50 items.
`rules (shape 1).all[].field`	string	yes	At most 120 characters.
`rules (shape 1).all[].op`	one of "eq", "neq", "contains", "not_contains", "starts_with", "ends_with", "gt", "gte", "lt", "lte", "is_set", "is_not_set", …	yes
`rules (shape 1).all[].value`	string or number or boolean or array of string or null	no
`rules (shape 2).any`	array of object	yes	At most 50 items.
`rules (shape 2).any[].field`	string	yes	At most 120 characters.
`rules (shape 2).any[].op`	one of "eq", "neq", "contains", "not_contains", "starts_with", "ends_with", "gt", "gte", "lt", "lte", "is_set", "is_not_set", …	yes
`rules (shape 2).any[].value`	string or number or boolean or array of string or null	no
`contacts_count`	integer or null	yes
`created_at`	string (date-time)	yes	An ISO 8601 timestamp with timezone, for example 2026-10-24T18:00:00.000Z.
`updated_at`	string (date-time)	yes	An ISO 8601 timestamp with timezone, for example 2026-10-24T18:00:00.000Z.

Errors: 400, 401, 403, 404, 409, 422, 429, 500, with the error body.

Examples

curl

curl https://api.minket.com/v1/segments/019a2b3c-4d5e-7f60-8a9b-0c1d2e3f4a5b \
  -H "Authorization: Bearer $MINKET_API_KEY"

TypeScript

const result = await minket.segments.get("019a2b3c-4d5e-7f60-8a9b-0c1d2e3f4a5b");

CLI

minket api getSegment 019a2b3c-4d5e-7f60-8a9b-0c1d2e3f4a5b

Python

from minket.api.segments import get_segment

result = get_segment.sync("019a2b3c-4d5e-7f60-8a9b-0c1d2e3f4a5b", client=client)

res, err := client.GetSegmentWithResponse(ctx, "019a2b3c-4d5e-7f60-8a9b-0c1d2e3f4a5b")

Update a segment

PATCH /v1/segments/{id}

Renames it or, for a dynamic segment, replaces its rules. The kind is fixed.

Operation updateSegment, SDK minket.segments.update. Keys: full access. Live keys only: test keys get 403 test_mode_only.

Parameters

Name	In	Type	Required	Description
`id`	path	string	yes	A UUID.

Request body

Field	Type	Required	Description
`name`	string	no	1 to 100 characters.
`kind`	one of "static", "dynamic"	no	Default `"static"`.
`rules`	object	no
`rules (shape 1).all`	array of object	yes	At most 50 items.
`rules (shape 1).all[].field`	string	yes	At most 120 characters.
`rules (shape 1).all[].op`	one of "eq", "neq", "contains", "not_contains", "starts_with", "ends_with", "gt", "gte", "lt", "lte", "is_set", "is_not_set", …	yes
`rules (shape 1).all[].value`	string or number or boolean or array of string or null	no
`rules (shape 2).any`	array of object	yes	At most 50 items.
`rules (shape 2).any[].field`	string	yes	At most 120 characters.
`rules (shape 2).any[].op`	one of "eq", "neq", "contains", "not_contains", "starts_with", "ends_with", "gt", "gte", "lt", "lte", "is_set", "is_not_set", …	yes
`rules (shape 2).any[].value`	string or number or boolean or array of string or null	no

Response

200 Success: Segment.

Field	Type	Required	Description
`id`	string	yes	A UUID.
`object`	"segment"	yes
`project_id`	string	yes	A UUID.
`name`	string	yes
`kind`	one of "static", "dynamic"	yes
`rules`	object or null	yes
`rules (shape 1).all`	array of object	yes	At most 50 items.
`rules (shape 1).all[].field`	string	yes	At most 120 characters.
`rules (shape 1).all[].op`	one of "eq", "neq", "contains", "not_contains", "starts_with", "ends_with", "gt", "gte", "lt", "lte", "is_set", "is_not_set", …	yes
`rules (shape 1).all[].value`	string or number or boolean or array of string or null	no
`rules (shape 2).any`	array of object	yes	At most 50 items.
`rules (shape 2).any[].field`	string	yes	At most 120 characters.
`rules (shape 2).any[].op`	one of "eq", "neq", "contains", "not_contains", "starts_with", "ends_with", "gt", "gte", "lt", "lte", "is_set", "is_not_set", …	yes
`rules (shape 2).any[].value`	string or number or boolean or array of string or null	no
`contacts_count`	integer or null	yes
`created_at`	string (date-time)	yes	An ISO 8601 timestamp with timezone, for example 2026-10-24T18:00:00.000Z.
`updated_at`	string (date-time)	yes	An ISO 8601 timestamp with timezone, for example 2026-10-24T18:00:00.000Z.

Errors: 400, 401, 403, 404, 409, 422, 429, 500, with the error body.

Examples

curl

curl -X PATCH https://api.minket.com/v1/segments/019a2b3c-4d5e-7f60-8a9b-0c1d2e3f4a5b \
  -H "Authorization: Bearer $MINKET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Paying customers"}'

TypeScript

const result = await minket.segments.update("019a2b3c-4d5e-7f60-8a9b-0c1d2e3f4a5b", {
  name: "Paying customers"
});

CLI

minket api updateSegment 019a2b3c-4d5e-7f60-8a9b-0c1d2e3f4a5b --body '{"name":"Paying customers"}'

Python

from minket.api.segments import update_segment
from minket.models import UpdateSegmentBody

result = update_segment.sync("019a2b3c-4d5e-7f60-8a9b-0c1d2e3f4a5b", client=client, body=UpdateSegmentBody.from_dict({"name":"Paying customers"}))

var body minket.UpdateSegmentJSONRequestBody
res, err := client.UpdateSegmentWithResponse(ctx, "019a2b3c-4d5e-7f60-8a9b-0c1d2e3f4a5b", body)

Delete a segment

DELETE /v1/segments/{id}

Operation deleteSegment, SDK minket.segments.delete. Keys: full access. Live keys only: test keys get 403 test_mode_only.

Parameters

Name	In	Type	Required	Description
`id`	path	string	yes	A UUID.

Response

200 Success: object.

Field	Type	Required
`object`	"segment"	yes
`id`	string	yes
`deleted`	true	yes

Errors: 400, 401, 403, 404, 409, 422, 429, 500, with the error body.

Examples

curl

curl -X DELETE https://api.minket.com/v1/segments/019a2b3c-4d5e-7f60-8a9b-0c1d2e3f4a5b \
  -H "Authorization: Bearer $MINKET_API_KEY"

TypeScript

const result = await minket.segments.delete("019a2b3c-4d5e-7f60-8a9b-0c1d2e3f4a5b");

CLI

minket api deleteSegment 019a2b3c-4d5e-7f60-8a9b-0c1d2e3f4a5b

Python

from minket.api.segments import delete_segment

result = delete_segment.sync("019a2b3c-4d5e-7f60-8a9b-0c1d2e3f4a5b", client=client)

res, err := client.DeleteSegmentWithResponse(ctx, "019a2b3c-4d5e-7f60-8a9b-0c1d2e3f4a5b")

List a segment's contacts

GET /v1/segments/{id}/contacts

Operation listSegmentContacts, SDK minket.segments.contacts.list. Keys: full access. Test keys work on test-mode data.

Parameters

Name	In	Type	Required	Description
`id`	path	string	yes	A UUID.
`limit`	query	integer	no	Default `20`.
`after`	query	string	no	A UUID.
`before`	query	string	no	A UUID.

Response

200 Success: object.

Field	Type	Required	Description
`object`	"list"	yes
`data`	array of object	yes
`data[].id`	string	yes	A UUID.
`data[].object`	"contact"	yes
`data[].project_id`	string	yes	A UUID.
`data[].email`	string	yes
`data[].first_name`	string or null	yes
`data[].last_name`	string or null	yes
`data[].unsubscribed`	boolean	yes
`data[].status`	one of "active", "unsubscribed", "bounced", "complained", "sunset"	yes
`data[].properties`	map of string or number or boolean or null	yes
`data[].last_sent_at`	string (date-time) or null	yes	An ISO 8601 timestamp with timezone, for example 2026-10-24T18:00:00.000Z.
`data[].last_opened_at`	string (date-time) or null	yes	An ISO 8601 timestamp with timezone, for example 2026-10-24T18:00:00.000Z.
`data[].last_clicked_at`	string (date-time) or null	yes	An ISO 8601 timestamp with timezone, for example 2026-10-24T18:00:00.000Z.
`data[].created_at`	string (date-time)	yes	An ISO 8601 timestamp with timezone, for example 2026-10-24T18:00:00.000Z.
`data[].updated_at`	string (date-time)	yes	An ISO 8601 timestamp with timezone, for example 2026-10-24T18:00:00.000Z.
`has_more`	boolean	yes

Errors: 400, 401, 403, 404, 409, 422, 429, 500, with the error body.

Examples

curl

curl https://api.minket.com/v1/segments/019a2b3c-4d5e-7f60-8a9b-0c1d2e3f4a5b/contacts \
  -H "Authorization: Bearer $MINKET_API_KEY"

TypeScript

const result = await minket.segments.contacts.list("019a2b3c-4d5e-7f60-8a9b-0c1d2e3f4a5b");

CLI

minket api listSegmentContacts 019a2b3c-4d5e-7f60-8a9b-0c1d2e3f4a5b

Python

from minket.api.segments import list_segment_contacts

result = list_segment_contacts.sync("019a2b3c-4d5e-7f60-8a9b-0c1d2e3f4a5b", client=client)

res, err := client.ListSegmentContactsWithResponse(ctx, "019a2b3c-4d5e-7f60-8a9b-0c1d2e3f4a5b", &minket.ListSegmentContactsParams{})

Add contacts to a static segment

POST /v1/segments/{id}/contacts

Operation addSegmentContacts, SDK minket.segments.contacts.add. Keys: full access. Live keys only: test keys get 403 test_mode_only.

Parameters

Name	In	Type	Required	Description
`id`	path	string	yes	A UUID.

Request body

Field	Type	Required	Description
`contact_ids`	array of string	no	At most 1000 items.
`emails`	array of string	no	At most 1000 items.

Response

200 Success: object.

Field	Type	Required
`object`	"segment"	yes
`id`	string	yes
`added`	integer	yes

Errors: 400, 401, 403, 404, 409, 422, 429, 500, with the error body.

Examples

curl

curl -X POST https://api.minket.com/v1/segments/019a2b3c-4d5e-7f60-8a9b-0c1d2e3f4a5b/contacts \
  -H "Authorization: Bearer $MINKET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"emails":["jane@example.com"]}'

TypeScript

const result = await minket.segments.contacts.add("019a2b3c-4d5e-7f60-8a9b-0c1d2e3f4a5b", {
  emails: [
    "jane@example.com"
  ]
});

CLI

minket api addSegmentContacts 019a2b3c-4d5e-7f60-8a9b-0c1d2e3f4a5b --body '{"emails":["jane@example.com"]}'

Python

from minket.api.segments import add_segment_contacts
from minket.models import AddSegmentContactsBody

result = add_segment_contacts.sync("019a2b3c-4d5e-7f60-8a9b-0c1d2e3f4a5b", client=client, body=AddSegmentContactsBody.from_dict({"emails":["jane@example.com"]}))

var body minket.AddSegmentContactsJSONRequestBody
res, err := client.AddSegmentContactsWithResponse(ctx, "019a2b3c-4d5e-7f60-8a9b-0c1d2e3f4a5b", body)

Remove contacts from a static segment

DELETE /v1/segments/{id}/contacts

Operation removeSegmentContacts, SDK minket.segments.contacts.remove. Keys: full access. Live keys only: test keys get 403 test_mode_only.

Parameters

Name	In	Type	Required	Description
`id`	path	string	yes	A UUID.

Request body

Field	Type	Required	Description
`contact_ids`	array of string	no	At most 1000 items.
`emails`	array of string	no	At most 1000 items.

Response

200 Success: object.

Field	Type	Required
`object`	"segment"	yes
`id`	string	yes
`removed`	integer	yes

Errors: 400, 401, 403, 404, 409, 422, 429, 500, with the error body.

Examples

curl

curl -X DELETE https://api.minket.com/v1/segments/019a2b3c-4d5e-7f60-8a9b-0c1d2e3f4a5b/contacts \
  -H "Authorization: Bearer $MINKET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"emails":["jane@example.com"]}'

TypeScript

const result = await minket.segments.contacts.remove("019a2b3c-4d5e-7f60-8a9b-0c1d2e3f4a5b", {
  emails: [
    "jane@example.com"
  ]
});

CLI

minket api removeSegmentContacts 019a2b3c-4d5e-7f60-8a9b-0c1d2e3f4a5b --body '{"emails":["jane@example.com"]}'

Python

from minket.api.segments import remove_segment_contacts
from minket.models import RemoveSegmentContactsBody

result = remove_segment_contacts.sync("019a2b3c-4d5e-7f60-8a9b-0c1d2e3f4a5b", client=client, body=RemoveSegmentContactsBody.from_dict({"emails":["jane@example.com"]}))

var body minket.RemoveSegmentContactsJSONRequestBody
res, err := client.RemoveSegmentContactsWithResponse(ctx, "019a2b3c-4d5e-7f60-8a9b-0c1d2e3f4a5b", body)

Updated 30 October 2026