The Create Segmentation Rule command allows you to define a new Advanced Segmentation Rule to use when sending campaigns. The Create Advanced Segmentation Rule command mirrors the functionality of the UI by defining an SQL like query. .
Arguments
The Create Segmentation Rule command requires the following arguments: Command, Realm, Password, Segmentation Type, Segmentation Rule Name, Rule(s), and List ID.
api_web?r=myrealm&p=mypass&c=createseg&segmentation_type=adv&segmentation_name=my+advanced+rule&list_id=5&rules=email=′jane@domain.com′
The command is ‘createseg', the realm is ‘myrealm’ and the password is ‘mypass’. The rule will be named ‘my advanced rule’ and will search the list for contact with email address 'jane@domain.com'.
The command creates an advanced segmentation rule and returns the segmentation rule id. The list_id is required in order to determine if the rule is valid. You may use any list in your realm.
You can define any size query in the advance segmentation rule. To add multiple rules, define each rule separated by either ‘AND’ or ‘OR’. The ‘rules’ argument must include the field name, comparison operator, and value. The field name can be any default contact data field or custom data field.
The Create Segmentation Rule command supports the following arguments:
|
Name |
Req? |
Description |
Argument |
|
Command |
Yes |
Defines the command to use. |
cmd=createseg c=createseg |
|
Realm |
Yes |
Name of the realm to run the command. This is required, and the command will fail if the realm and password do not match. |
realm=[realm_name] r=[realm_name] |
|
Password |
Yes |
Authentication code for API access. This is required, and the command will fail if the realm and password do not match. |
pwd=[password] p=[password] |
|
Segmentation Rule Name |
Yes |
Name of the advanced segmentation rule to create. To include spaces in the name, replace space with '+' or '%20' to avoid possible issues with spaces in a URL. |
segmentation_name=[segmentation_name] |
|
Segmentation Type |
Yes |
Specifies the type of segmentation rule to create. Define as type 'adv' for advanced. |
segmentation_type=adv |
|
List ID |
Yes |
Identifier of the list to validate the rule against. List must be in designated realm. |
list_id=[list_id] |
|
Segmentation Rules |
Yes |
Define the query to evaluate. |
rules=[query] |
|
Description |
|
Short text description of the Segmentation Rule. |
description=[text] |
Example
Using createseg with all commands and arguments (please note the command is wrapped for display purposes only).
AND operator with two rules:
api_web?r=myrealm&p=mypass&c=createseg&segmentation_type=adv&list_id=5&segmentation_name=my+advanced+rule1&description=Advanced+rule+1&rules=email=′jane@domain.com′%20and%20first_name%20not+endswith%20′y′
No operator with one rule:
api_web?r=myrealm&p=mypass&c=createseg&segmentation_type=adv&list_id=5&segmentation_name=my+advanced+rule2&description=Advanced+rule+2&rules=last_sent_date%20>%20′2007-10-22′
Combination of operators and grouped rules:
api_web?r=myrealm&p=mypass&c=createseg&segmentation_type=adv&list_id=5&segmentation_name=my+advanced+rule3&description=Advanced+rule+3 &rules=(last_sent_date%20>%20′2007-10-22′%20or%20 last_sent_date%20not+exists)%20and%20(′jane@domain.com′%20and%20 first_name%20not+endswith%20′y′%20and%20last_name%20contains%20′doe′)
Successful results for one call return, where ‘10’ is the ID of the new rule:
SUCCESS: 10
Results
The Create Segmentation Rule command outputs either a SUCCESS or FAILURE message.
SUCCESS
The Create Segmentation Rule command success message returns the SUCCESS message and the id of the new rule. The result format is:
SUCCESS: [segmentation_rule_id]
FAILURE
A Create Segmentation Rule command will fail if a rule with the same name already exists or invalid data is defined. The result format is:
FAILURE: [Reason]