Segment API Documentation

Segment management endpoints for creating, updating, and managing subscriber segments within email lists.

Create a Segment

POST /api.php

API Usage Notes

• Authentication required: User API Key
• Required permissions: Segment.Create
• Legacy endpoint access via /api.php only (no v1 REST alias configured)

Request Body Parameters:

Parameter	Type	Required	Description
Command	String	Yes	API command: segment.create
SessionID	String	No	Session ID obtained from login
APIKey	String	No	API key for authentication
SubscriberListID	Integer	Yes	ID of the subscriber list
SegmentName	String	Yes	Name of the segment
SegmentOperator	String	Yes	Connector between top-level rule groups: and or or. It is not applied uniformly to every rule — the connector alternates with nesting depth (see the note below).
SegmentRuleField	Array	No	Array of rule field names (old style)
SegmentRuleOperator	Array	No	Array of rule operators (old style)
SegmentRuleFilter	Array	No	Array of rule filter values (old style)
RulesJson	String	No	Segment rules in JSON format
Randomness	Boolean	No	Pick a random audience matching the segment rules. Accepts true/false/yes/no/1/0. Defaults to false. Persisted as the Randomness key inside the segment's Options JSON blob (round-trips via Segments.Get).
RandomnessAudienceSize	Integer	No	Maximum number of subscribers to pick when Randomness is enabled. Non-numeric values silently coerce to 0. Defaults to 0. Persisted as the RandomnessAudienceSize key inside the segment's Options JSON blob.

SegmentOperator alternates with nesting depth

SegmentOperator sets the connector between top-level groups in RulesJson. It is not applied to every rule uniformly — the connector flips at each level of nesting:

SegmentOperator	Between groups	Inside one group	Inside a sub-group
and	AND	OR	AND
or	OR	AND	OR

So SegmentOperator: "or" with several rules in a single RulesJson group ANDs those rules together. To OR a set of rules, put each one in its own group. The structure of RulesJson — not SegmentOperator alone — determines the resolved audience.

Only three levels are evaluated (groups, sub-groups, and their rules); anything nested deeper is ignored by the segment engine. Changing SegmentOperator on an existing segment re-resolves its audience in both directions, since the within-group connector flips as well.

Example Request

curl -X POST https://example.com/api.php \
  -H "Content-Type: application/json" \
  -d '{
    "Command": "segment.create",
    "SessionID": "your-session-id",
    "SubscriberListID": 123,
    "SegmentName": "Active Subscribers",
    "SegmentOperator": "and",
    "RulesJson": "{\"rules\":[{\"field\":\"status\",\"operator\":\"equals\",\"value\":\"active\"}]}",
    "Randomness": true,
    "RandomnessAudienceSize": 500
  }'

Success Response

{
  "Success": true,
  "ErrorCode": 0,
  "ErrorText": "",
  "SegmentID": 456
}

Error Response

{
  "Success": false,
  "ErrorCode": [1, 2, 3],
  "ErrorText": ["Missing subscriber list id", "Missing segment name", "Missing segment operator"]
}

Error Codes

0: Success
1: Missing subscriber list id
2: Missing segment name
3: Missing segment operator
4: List not found or doesn't belong to user

Update a Segment

POST /api.php

API Usage Notes

• Authentication required: User API Key
• Required permissions: Segment.Update
• Legacy endpoint access via /api.php only (no v1 REST alias configured)

Request Body Parameters:

Parameter	Type	Required	Description
Command	String	Yes	API command: segment.update
SessionID	String	No	Session ID obtained from login
APIKey	String	No	API key for authentication
SegmentID	Integer	Yes	ID of the segment to update
SegmentName	String	Yes	Name of the segment
SubscriberListID	Integer	No	ID of the subscriber list (to move segment). Must be a numeric ID of a list owned by the authenticated user — otherwise the update aborts with error code 6. Non-numeric values (e.g. 12abc, 0) are silently ignored and the segment keeps its current list.
SegmentOperator	String	No	Connector between top-level rule groups: and or or. It is not applied uniformly to every rule — the connector alternates with nesting depth (see the note under segment.create). Changing it re-resolves the segment's audience, because the connector inside each group flips too.
SegmentRuleField	Array	No	Array of rule field names (old style)
SegmentRuleOperator	Array	No	Array of rule operators (old style)
SegmentRuleFilter	Array	No	Array of rule filter values (old style)
RulesJson	String	No	Segment rules in JSON format
Randomness	Boolean	No	Pick a random audience matching the segment rules. Accepts true/false/yes/no/1/0. When this parameter is omitted (or sent as an empty string) along with RandomnessAudienceSize, the segment's existing Options value is preserved as-is. When at least one of the two randomness params is provided, the missing one is read from the segment's existing Options blob (no silent reset to defaults).
RandomnessAudienceSize	Integer	No	Maximum number of subscribers to pick when Randomness is enabled. Non-numeric values silently coerce to 0. When this parameter is omitted (or sent as an empty string) along with Randomness, the segment's existing Options value is preserved as-is. When at least one of the two randomness params is provided, the missing one is read from the segment's existing Options blob.

Example Request

curl -X POST https://example.com/api.php \
  -H "Content-Type: application/json" \
  -d '{
    "Command": "segment.update",
    "SessionID": "your-session-id",
    "SegmentID": 456,
    "SegmentName": "Updated Active Subscribers",
    "SegmentOperator": "or",
    "Randomness": true,
    "RandomnessAudienceSize": 500
  }'

Success Response

{
  "Success": true,
  "ErrorCode": 0,
  "ErrorText": ""
}

Error Response

{
  "Success": false,
  "ErrorCode": [1, 2, 4],
  "ErrorText": ["Missing segment id", "Missing segment name", "Invalid segment id"]
}

Error Codes

0: Success
1: Missing segment id
2: Missing segment name
4: Invalid segment id
5: Invalid segment operator
6: Invalid subscriber list id

SubscriberListID ownership

When SubscriberListID is supplied, the target list is looked up scoped to the authenticated user. A list belonging to another account is therefore indistinguishable from one that does not exist — both return Success: false with ErrorCode: [6] and ErrorText: ["Invalid subscriber list id"], and the update aborts before any change is written.

This response is returned with HTTP 200, like every other error from this legacy endpoint — always branch on the Success / ErrorCode fields in the body, not on the HTTP status.

Non-numeric values ("12abc", "0") fail the numeric guard and are silently ignored: no error is raised and the segment keeps its existing list. Ownership of the segment itself is checked separately and reports error code 4 (Invalid segment id).

Copy Segments

POST /api.php

API Usage Notes

• Authentication required: User API Key
• Required permissions: Segment.Create
• Legacy endpoint access via /api.php only (no v1 REST alias configured)

Request Body Parameters:

Parameter	Type	Required	Description
Command	String	Yes	API command: segments.copy
SessionID	String	No	Session ID obtained from login
APIKey	String	No	API key for authentication
SourceListID	Integer	Yes	ID of the source subscriber list
TargetListID	Integer	Yes	ID of the target subscriber list

Example Request

curl -X POST https://example.com/api.php \
  -H "Content-Type: application/json" \
  -d '{
    "Command": "segments.copy",
    "SessionID": "your-session-id",
    "SourceListID": 123,
    "TargetListID": 789
  }'

Success Response

{
  "Success": true,
  "ErrorCode": 0,
  "ErrorText": ""
}

Error Response

{
  "Success": false,
  "ErrorCode": [1, 2, 4],
  "ErrorText": ["Missing required field"]
}

Error Codes

0: Success
1: Missing sourcelistid
2: Missing targetlistid
4: Invalid source subscriber id or Invalid target subscriber id

Delete Segments

POST /api.php

API Usage Notes

• Authentication required: User API Key
• Required permissions: Segments.Delete
• Legacy endpoint access via /api.php only (no v1 REST alias configured)

Request Body Parameters:

Parameter	Type	Required	Description
Command	String	Yes	API command: segments.delete
SessionID	String	No	Session ID obtained from login
APIKey	String	No	API key for authentication
Segments	String	Yes	Comma-separated list of segment IDs to delete

Example Request

curl -X POST https://example.com/api.php \
  -H "Content-Type: application/json" \
  -d '{
    "Command": "segments.delete",
    "SessionID": "your-session-id",
    "Segments": "456,457,458"
  }'

Success Response

{
  "Success": true,
  "ErrorCode": 0,
  "ErrorText": ""
}

Error Response

{
  "Success": false,
  "ErrorCode": [1],
  "ErrorText": ["Segment ids are missing"]
}

Error Codes

0: Success
1: Segment ids are missing

Get Segments

POST /api.php

API Usage Notes

• Authentication required: User API Key
• Required permissions: Segments.Get
• Legacy endpoint access via /api.php only (no v1 REST alias configured)

Request Body Parameters:

Parameter	Type	Required	Description
Command	String	Yes	API command: segments.get
SessionID	String	No	Session ID obtained from login
APIKey	String	No	API key for authentication
SubscriberListID	Integer	Yes	ID of the subscriber list
SegmentID	Integer	No	ID of specific segment to retrieve
IncludeTotals	Boolean	No	Include total counts (default: true)
OrderField	String	No	Field to order by: SegmentName, SegmentID, SegmentOperator, SubscriberCount, SubscriberCountLastCalculatedOn (default: SegmentName)
OrderType	String	No	Sort order: ASC or DESC (default: DESC)

Example Request

curl -X POST https://example.com/api.php \
  -H "Content-Type: application/json" \
  -d '{
    "Command": "segments.get",
    "SessionID": "your-session-id",
    "SubscriberListID": 123,
    "OrderField": "SegmentName",
    "OrderType": "ASC"
  }'

Success Response

{
  "Success": true,
  "ErrorCode": 0,
  "ErrorText": "",
  "TotalSegmentCount": 5,
  "Segments": [
    {
      "SegmentID": 456,
      "SegmentName": "Active Subscribers",
      "SegmentOperator": "and",
      "SubscriberCount": 1250,
      "SegmentRules": "...",
      "SegmentRulesJson": "{...}"
    }
  ]
}

Error Response

{
  "Success": false,
  "ErrorCode": [1],
  "ErrorText": "Missing subscriber list id"
}

Error Codes

0: Success
1: Missing subscriber list id