Skip to content

Segments

Create a New Segment

POST /api.php

This endpoint is used to create a new segment within a subscriber list. A segment allows you to categorize your subscribers based on specific criteria.

Request Body Parameters:

ParameterDescriptionRequired?
SessionIDThe ID of the user's current sessionYes
APIKeyThe user's API key. Either SessionID or APIKey must be provided.Yes
CommandSegment.CreateYes
SubscriberListIDThe unique identifier for the subscriber list to which the segment belongsYes
SegmentNameThe name of the segment to be createdYes
SegmentOperatorThe operator used to combine segment rules (e.g., AND, OR)Yes
SegmentRuleFieldAn array of fields to be used in segment rulesNo
SegmentRuleOperatorAn array of operators to be used in segment rulesNo
SegmentRuleFilterAn array of values to filter the fields in segment rulesNo
RulesJsonA JSON string representing the segment rulesNo
bash
curl -X POST https://example.com/api.php \
  -d 'SessionID=exampleSessionId' \
  -d 'APIKey=exampleApiKey' \
  -d 'Command=Segment.Create' \
  -d 'SubscriberListID=123' \
  -d 'SegmentName=My New Segment' \
  -d 'SegmentOperator=AND' \
  -d 'RulesJson={"field":"email","operator":"contains","value":"@example.com"}'
json
{
  "Success": true,
  "ErrorCode": 0,
  "ErrorText": "",
  "SegmentID": 456
}
json
{
  "Success": false,
  "ErrorCode": [1],
  "ErrorText": ["Missing subscriber list id"]
}
txt
1: Missing subscriber list id
2: Missing segment name
3: Missing segment operator
4: The target list does not exist or does not belong to the user

NOTICE

Please note that the SegmentRuleField, SegmentRuleOperator, and SegmentRuleFilter parameters are arrays and should be used to define complex segment rules. If you provide the RulesJson parameter, it should be a JSON string that represents the segment rules in a structured format.

Update Segment Information

POST /api.php

This endpoint allows you to update the information of an existing segment. You can modify the segment's name, operator, associated subscriber list, and rules.

Request Body Parameters:

ParameterDescriptionRequired?
SessionIDThe ID of the user's current sessionYes
APIKeyThe user's API key. Either SessionID or APIKey must be provided.Yes
CommandSegment.UpdateYes
SegmentIDThe unique identifier for the segment to be updatedYes
SegmentNameThe new name for the segmentYes
SubscriberListIDThe ID of the subscriber list associated with the segment (optional)No
SegmentOperatorThe logical operator to be used for the segment rules (and/or)No
SegmentRuleFieldAn array of fields used in segment rules (optional)No
SegmentRuleOperatorAn array of operators used in segment rules (optional)No
SegmentRuleFilterAn array of filter values used in segment rules (optional)No
RulesJsonJSON representation of the segment rules (optional)No
bash
curl -X POST https://example.com/api.php \
  -d 'SessionID=exampleSessionId' \
  -d 'APIKey=exampleApiKey' \
  -d 'Command=Segment.Update' \
  -d 'SegmentID=123' \
  -d 'SegmentName=Updated Segment Name' \
  -d 'SegmentOperator=and'
json
{
  "Success": true,
  "ErrorCode": 0,
  "ErrorText": ""
}
json
{
  "Success": false,
  "ErrorCode": [1],
  "ErrorText": ["Missing segment id"]
}
txt
1: Missing segment id
2: Missing segment name
3: Missing segment operator
4: Invalid segment id
5: Invalid segment operator

Copy Segments from One List to Another

POST /api.php

This endpoint allows you to copy segments from a source subscriber list to a target subscriber list. It is useful for replicating segmentation rules across different lists within the same user account.

Request Body Parameters:

ParameterDescriptionRequired?
SessionIDThe ID of the user's current sessionYes
APIKeyThe user's API key. Either SessionID or APIKey must be provided.Yes
CommandSegments.CopyYes
SourceListIDThe ID of the source subscriber list from which segments will be copiedYes
TargetListIDThe ID of the target subscriber list to which segments will be copiedYes
bash
curl -X POST https://example.com/api.php \
  -d 'SessionID=exampleSessionId' \
  -d 'APIKey=exampleApiKey' \
  -d 'Command=Segments.Copy' \
  -d 'SourceListID=123' \
  -d 'TargetListID=456'
json
{
  "Success": true,
  "ErrorCode": 0,
  "ErrorText": ""
}
json
{
  "Success": false,
  "ErrorCode": [1],
  "ErrorText": ["Required field missing: SourceListID"]
}
txt
1: Required field missing: SourceListID
2: Required field missing: TargetListID
4: Invalid subscriber list ID

Delete Segments

POST /api.php

This endpoint allows for the deletion of one or more segments associated with a user. The user must provide the segment IDs to be deleted.

Request Body Parameters:

ParameterDescriptionRequired?
SessionIDThe ID of the user's current sessionYes
APIKeyThe user's API key. Either SessionID or APIKey must be provided.Yes
CommandSegments.DeleteYes
SegmentsComma-separated list of segment IDs to be deletedYes
bash
curl -X POST https://example.com/api.php \
  -d 'SessionID=exampleSessionId' \
  -d 'APIKey=exampleApiKey' \
  -d 'Command=Segments.Delete' \
  -d 'Segments=1,2,3'
json
{
  "Success": true,
  "ErrorCode": 0,
  "ErrorText": ""
}
json
{
  "Success": false,
  "ErrorCode": {
    "segments": 1
  },
  "ErrorText": ["Segment ids are missing"]
}
txt
1: Segment ids are missing

NOTICe

  • Please note that the Segments parameter is a comma-separated list of segment IDs that the user wishes to delete.
  • If the Segments parameter is missing or invalid, an error response will be returned with the appropriate error code and message.

Retrieve Subscriber List Segments

POST /api.php

This endpoint retrieves all segments associated with a specific subscriber list for the authenticated user.

Request Body Parameters:

ParameterDescriptionRequired?
SessionIDThe ID of the user's current sessionYes
APIKeyThe user's API key. Either SessionID or APIKey must be provided.Yes
CommandSegments.GetYes
SubscriberListIDThe unique identifier for the subscriber listYes
OrderFieldThe field by which to order the segmentsNo
OrderTypeThe type of ordering to apply (e.g., ASC, DESC)No
bash
curl -X POST https://example.com/api.php \
  -H "Content-Type: application/json" \
  -d '{
        "SessionID": "your-session-id",
        "APIKey": "your-api-key",
        "Command": "Segments.Get",
        "SubscriberListID": "12345",
        "OrderField": "SegmentName",
        "OrderType": "ASC"
      }'
json
{
  "Success": true,
  "ErrorCode": 0,
  "ErrorText": "",
  "TotalSegmentCount": 5,
  "Segments": [
    {
      "SegmentID": "1",
      "SegmentName": "Segment A",
      "CreationDate": "2023-01-01",
      "LastUpdated": "2023-01-05"
    },
    {
      "SegmentID": "2",
      "SegmentName": "Segment B",
      "CreationDate": "2023-02-01",
      "LastUpdated": "2023-02-05"
    }
    // ... other segments
  ]
}
json
{
  "Success": false,
  "ErrorCode": 1,
  "ErrorText": "Missing subscriber list id"
}
txt
1: Missing subscriber list id

NOTICE

  • Please note that the OrderField and OrderType parameters are optional and can be used to sort the returned segments list.
  • If not provided, the default sorting will be applied.
  • The SubscriberListID is a mandatory parameter, and failure to provide it will result in an error response.

Any questions? Contact us.