The Segmentation API allows you to create, retrieve, update, and delete subscriber segments through the API.

Segments can be used to group subscribers based on list membership, subscription status, bounce status, verification status, country, email address, open activity, click activity, campaigns, browser/OS information, and other segmentation rules.

Available Methods

Method	Endpoint	Description
GET	`/getSegment`	Retrieve a single segment
GET	`/getSegments`	Retrieve available segments
POST	`/addSegment`	Create a new segment
POST	`/updateSegment`	Update an existing segment
POST	`/deleteSegment`	Delete a segment

All requests must use the same API authentication method as the other API functions.

Add Segment

Creates a new subscriber segment.

Endpoint

POST /addSegment

Required Parameter

Parameter	Description
`segment_label`	Name of the segment

General Filter Parameters

Parameter	Description

`list_id_fk[]`	One or more mailing list IDs
`unsubscribed`	Filter by unsubscribe status
`bounced`	Filter by bounce status
`verification_status`	Filter by email verification status
`geo_country[]`	Filter by geographical country
`delivery_status`	Filter by delivery status
`subscriber_name`	Filter according to subscriber name availability
`country[]`	Filter by subscriber country
`email_contains`	Email address must contain this value
`email_dont_contains`	Email address must not contain this value
`created_after_date`	Subscribers created after this date
`created_before_date`	Subscribers created before this date
`segment_condition`	Rule matching method

Unsubscribe Status

Values for unsubscribed:

Value	Meaning
`0`	All
`1`	Unsubscribed
`2`	Subscribed

Bounce Status

Values for bounced:

Value	Meaning
`0`	All
`1`	Hard bounced
`2`	Soft bounced
`3`	Hard or soft bounced
`4`	Exclude hard and soft bounced
`5`	Exclude hard bounced
`6`	Exclude soft bounced

Verification Status

Values for verification_status:

Value	Meaning
Empty	All
`1`	Verified
`2`	Does not exist

Delivery Status

Values for delivery_status:

Value	Meaning
`0`	All
`1`	Relayed
`2`	Failed
`3`	Not set

Subscriber Name

Values for subscriber_name:

Value	Meaning
`0`	All
`1`	Has first name
`2`	Has last name
`3`	Has first and last name
`4`	Without first name
`5`	Without last name
`6`	Without first and last name
`7`	First or last name is present
`8`	First or last name is absent

Open Activity Filters

Segments can be created according to subscriber email-open activity.

Parameter	Description
`opened`	Open activity status
`opened_country[]`	Opened from selected countries
`exclude_opened_country[]`	Exclude opens from selected countries
`opened_region[]`	Opened from selected regions
`opened_city[]`	Opened from selected cities
`opened_zip[]`	Opened from selected ZIP/postal codes
`opened_browser[]`	Browser used when opening
`opened_os[]`	Operating system used when opening
`opened_after_date`	Opened after date
`opened_after_time`	Opened after time
`opened_before_date`	Opened before date
`opened_before_time`	Opened before time
`opened_campaign[]`	Filter opens by campaign

Values for opened:

Value	Meaning
`0`	All
`1`	Opened
`2`	Unopened

Click Activity Filters

Segments can also be created according to subscriber click activity.

Parameter	Description
`clicked`	Click activity status
`clicked_country[]`	Clicked from selected countries
`clicked_region[]`	Clicked from selected regions
`clicked_city[]`	Clicked from selected cities
`clicked_zip[]`	Clicked from selected ZIP/postal codes
`clicked_browser[]`	Browser used for click
`clicked_os[]`	Operating system used for click
`clicked_after_date`	Clicked after date
`clicked_after_time`	Clicked after time
`clicked_before_date`	Clicked before date
`clicked_before_time`	Clicked before time
`clicked_campaign[]`	Filter clicks by campaign
`clicked_links[]`	Filter according to links clicked

Values for clicked:

Value	Meaning
`0`	All
`1`	Clicked
`2`	Not clicked

Segment Rule Matching

The segment_condition parameter determines how multiple segment conditions are evaluated.

Value	Description
`1`	Match all conditions (AND)
`2`	Match any condition (OR)

For example:

segment_condition=1
country[]=UNITED STATES
opened=1

This requests subscribers matching all supplied conditions.

Add Segment Example

Create a segment containing Gmail subscribers from the United States who have opened an email:

curl -X POST "https://YOUR-DOMAIN/API-PATH/addSegment" \
  -d "segment_label=USA Gmail Openers" \
  -d "list_id_fk[]=10" \
  -d "country[]=UNITED STATES" \
  -d "[email protected]" \
  -d "opened=1" \
  -d "segment_condition=1"

Example successful response:

{
  "Segment ID": 123
}

Save the returned Segment ID. It can be used with the other segmentation API methods.

Get Segment

Returns information about a single segment and its saved segmentation parameters.

Endpoint

GET /getSegment

Parameters

Parameter	Required	Description
`segment_id`	Yes	Segment ID

Example

GET /getSegment?segment_id=123

Example response:

{
  "schedule_segment_id": "123",
  "segment_label": "USA Gmail Openers",
  "total": "1500",
  "params": {
    "list_id_fk": [
      "10"
    ],
    "country": [
      "US"
    ],
    "email_contains": "@gmail.com",
    "opened": "1",
    "segment_condition": "1"
  }
}

Access to the segment is subject to the authenticated account and user permissions.

Get Segments

Returns segments available to the authenticated account/user.

Endpoint

GET /getSegments

Optional Parameters

Parameter	Description
`start`	Starting record for pagination
`records`	Number of records to return
`parent_segment_id`	Return segments belonging to a particular parent segment
`search`	Search segment names

The default number of records is 100. A maximum of 1000 records can be requested in one API call.

Example

GET /getSegments?start=0&records=100

Search for segments:

GET /getSegments?search=Gmail&start=0&records=100

Update Segment

Updates an existing segment.

Endpoint

POST /updateSegment

Required Parameter

Parameter	Description
`segment_id`	Segment to update

You may provide schedule_segment_id instead of segment_id for compatibility.

The request can contain segment_label and any of the segmentation parameters supported by addSegment.

Example

curl -X POST "https://YOUR-DOMAIN/API-PATH/updateSegment" \
  -d "segment_id=123" \
  -d "segment_label=USA Gmail Openers - Updated" \
  -d "list_id_fk[]=10" \
  -d "country[]=UNITED STATES" \
  -d "[email protected]" \
  -d "opened=1" \
  -d "segment_condition=1"

Example successful response:

{
  "Segment ID": 123
}

When segmentation parameters are supplied during an update, they become the new parameters for the segment. If no segmentation parameters are supplied, the existing segment parameters are retained.

Delete Segment

Permanently deletes a segment.

Endpoint

POST /deleteSegment

Required Parameter

Parameter	Description
`segment_id`	Segment ID to delete

Example

curl -X POST "https://YOUR-DOMAIN/API-PATH/deleteSegment" \
  -d "segment_id=123"

Example successful response:

{
  "Segment ID": 123
}

The API checks that the authenticated user has access to the segment before deleting it.

Additional Examples

Subscribers from Multiple Lists

curl -X POST "https://YOUR-DOMAIN/API-PATH/addSegment" \
  -d "segment_label=Multiple Lists" \
  -d "list_id_fk[]=10" \
  -d "list_id_fk[]=20" \
  -d "list_id_fk[]=30"

Non-Openers

curl -X POST "https://YOUR-DOMAIN/API-PATH/addSegment" \
  -d "segment_label=Non Openers" \
  -d "list_id_fk[]=10" \
  -d "opened=2"

Clicked Subscribers

curl -X POST "https://YOUR-DOMAIN/API-PATH/addSegment" \
  -d "segment_label=Clicked Subscribers" \
  -d "list_id_fk[]=10" \
  -d "clicked=1"

Exclude Bounced Subscribers

curl -X POST "https://YOUR-DOMAIN/API-PATH/addSegment" \
  -d "segment_label=Active Subscribers" \
  -d "list_id_fk[]=10" \
  -d "bounced=4"

Date-Based Segment

curl -X POST "https://YOUR-DOMAIN/API-PATH/addSegment" \
  -d "segment_label=Recent Subscribers" \
  -d "list_id_fk[]=10" \
  -d "created_after_date=2026-09-01"

Multiple Conditions

curl -X POST "https://YOUR-DOMAIN/API-PATH/addSegment" \
  -d "segment_label=Engaged US Subscribers" \
  -d "list_id_fk[]=10" \
  -d "country[]=UNITED STATES" \
  -d "opened=1" \
  -d "clicked=1" \
  -d "segment_condition=1"

Error Responses

If a required parameter is missing, an error is returned.

For example:

segment_id is required

or:

segment_label is required

The API can also return:

Segment not found or access denied

This means that the segment does not exist or the authenticated user does not have permission to access it.

When creating or updating a segment using mailing lists, the API also verifies access to the supplied list IDs.

Notes

Array parameters should use the [] format when sending multiple values.

Example:

list_id_fk[]=10
list_id_fk[]=20

country[]=UNITED STATES 
country[]=CANADA

Segment definitions are stored using the same segmentation parameters as the web-based segmentation interface.

Creating a segment stores its definition. Subscriber counting and retrieval of subscribers matching a segment require the segment execution/counting API functions when those functions are enabled.

Databáze řešení

Kategorie

Kategorie

Segmentation

Available Methods

Add Segment

Endpoint

Required Parameter

General Filter Parameters

Unsubscribe Status

Bounce Status

Verification Status

Delivery Status

Subscriber Name

Open Activity Filters

Click Activity Filters

Segment Rule Matching

Add Segment Example

Get Segment

Endpoint

Parameters

Example

Get Segments

Endpoint

Optional Parameters

Example

Update Segment

Endpoint

Required Parameter

Example

Delete Segment

Endpoint

Required Parameter

Example

Additional Examples

Subscribers from Multiple Lists

Non-Openers

Clicked Subscribers

Exclude Bounced Subscribers

Date-Based Segment

Multiple Conditions

Error Responses

Notes

Související články

Podpora