campaignSegmentTest – v1.3

 campaignSegmentTest(string apikey, string list_id, array options)

Allows one to test their segmentation rules before creating a campaign using them

Section
Campaign Related

Parameters
apikey	a valid API Key for your user account. Get by visiting your API dashboard
list_id	the list to test segmentation on - get lists using lists()
options	with 2 keys: string "match" controls whether to use AND or OR when applying your options - expects "any" (for OR) or "all" (for AND) array "conditions" - up to 10 different criteria to apply while segmenting. Each criteria row must contain 3 keys - "field", "op", and "value" - and possibly a fourth, "extra", based on these definitions:   Field = "date" : Select based on signup date Valid Op(eration): eq (is) / gt (after) / lt (before) Valid Values: string last_campaign_sent uses the date of the last campaign sent string campaign_id - uses the send date of the campaign that carriers the Id submitted - see campaigns() string YYYY-MM-DD - any date in the form of YYYY-MM-DD - note: anything that appears to start with YYYY will be treated as a date   Field = "last_changed" : Select based on subscriber record last changed date Valid Op(eration): eq (is) / gt (after) / lt (before) Valid Values: string formatted_date - any date in the form of YYYY-MM-DD or YYYY-MM-DD HH:ii:ss (Year-Month-Day Hours:minutes:seconds)   Field = "interests-X": where X is the Grouping Id from listInterestGroupings() Valid Op(erations): one / none / all Valid Values: a comma delimited of interest groups for the list - see listInterestGroupings()   Field = "aim" Valid Op(erations): open / noopen / click / noclick Valid Values: "any" or a valid AIM-enabled Campaign that has been sent   Field = "rating" : allows matching based on list member ratings Valid Op(erations): eq (=) / ne (!=) / gt (>) / lt (<) Valid Values: a number between 0 and 5   Field = "ecomm_prod" or "ecomm_prod": allows matching product and category names from purchases Valid Op(erations): eq (=) / ne (!=) / gt (>) / lt (<) / like (like '%blah%') / nlike (not like '%blah%') / starts (like 'blah%') / ends (like '%blah') Valid Values: any string   Field = "ecomm_spent_one" or "ecomm_spent_all" : allows matching purchase amounts on a single order or all orders Valid Op(erations): gt (>) / lt (<) Valid Values: a number   Field = "ecomm_date" : allow matching based on order dates Valid Op(eration): eq (is) / gt (after) / lt (before) Valid Values: string YYYY-MM-DD - any date in the form of YYYY-MM-DD   Field = "social_gender" : allows matching against the gender acquired from SocialPro Valid Op(eration): eq (is) / ne (is not) Valid Values: male, female   Field = "social_age" : allows matching against the age acquired from SocialPro Valid Op(erations): eq (=) / ne (!=) / gt (>) / lt (<) Valid Values: any number   Field = "social_influence" : allows matching against the influence acquired from SocialPro Valid Op(erations): eq (=) / ne (!=) / gt (>) / lt (<) Valid Values: a number between 0 and 5   Field = "social_network" : Valid Op(erations): member (is a member of) / notmember (is not a member of) Valid Values: twitter, facebook, myspace, linkedin, flickr   Field = "static_segment" : Valid Op(erations): eq (is in) / ne (is not in) Valid Values: an int - get from listStaticSegments()   Field = "default_location" : the location we automatically assign to a subscriber based on where we've seen their activity originate Valid Op(erations): ipgeostate (within a US state) / ipgeonotstate (not within a US state) / ipgeocountry (within a country) / ipgeonotcountry (not within a country) / ipgeoin (within lat/lng parameters) / ipgeonotin (not within lat/lng parameters) Valid Values: string ipgeostate/ipgeonotstate a full US state name (not case sensitive) string ipgeocountry/ipgeonotcountry an ISO3166 2 digit country code (not case sensitive) int ipgeoin/ipgeonotin a distance in miles centered around a point you must specify by also passing lat (latitude) and lng (longitude) parameters   Field = A Birthday type Merge Var. Use Merge0-Merge30 or the Custom Tag you've setup for your merge field - see listMergeVars(). Note, Brithday fields can only use with the operations listed here. Valid Op(erations): eq (=) / starts (month equals) / ends (day equals) Valid Values: Any valid number for the operation being checked.   Field = A Zip type Merge Var. Use Merge0-Merge30 or the Custom Tag you've setup for your merge field - see listMergeVars(). Note, Zip fields can only use with the operations listed here. Valid Op(erations): eq (=) / ne (!=) / geoin (US only) Valid Values: For eq (=) / ne, a Zip Code. For geoin, a radius in miles Extra Value: Only for geoin - the Zip Code to be used as the center point   Field = An Address type Merge Var. Use Merge0-Merge30 or the Custom Tag you've setup for your merge field - see listMergeVars(). Note, Address fields can only use with the operations listed here. Valid Op(erations): like (like '%blah%') / nlike (not like '%blah%') / geoin Valid Values: For like and nlike, a string. For geoin, a radius in miles Extra Value: Only for geoin - the Zip Code to be used as the center point   Default Field = A Merge Var. Use Merge0-Merge30 or the Custom Tag you've setup for your merge field - see listMergeVars() Valid Op(erations): eq (=) / ne (!=) / gt (>) / lt (<) / like (like '%blah%') / nlike (not like '%blah%') / starts (like 'blah%') / ends (like '%blah') Valid Values: any string

Returns
int	total The total number of subscribers matching your segmentation options

Examples (2)

download example code

[1] mcapi_campaignSegmentTest.php

<?php
/**
This Example shows how to test a List Segment for use with a new campaign 
via the MCAPI class.
**/
require_once 'inc/MCAPI.class.php';
require_once 'inc/config.inc.php'; //contains apikey
 
$api = new MCAPI($apikey);
 
$conditions = array();
$conditions[] = array('field'=>'email', 'op'=>'like', 'value'=>'mailchimp');
$opts = array('match'=>'all', 'conditions'=>$conditions);
 
$retval = $api->campaignSegmentTest($listId, $opts );
 
if ($api->errorCode){
	echo "Unable to Segment Campaign!";
	echo "\n\tCode=".$api->errorCode;
	echo "\n\tMsg=".$api->errorMessage."\n";
} else {
	echo "Your Segement matched [".$retval."] members.\n";
}
 
?>
 

[2] xml-rpc_campaignSegmentTest.php

<?php
/**
This Example shows how to test a List Segment for use with a new campaign using 
XML-RPC.
Note that we are using the PEAR XML-RPC2 client and recommend others do as well.
**/
require_once 'XML/RPC2/Client.php';
require_once 'inc/config.inc.php';
try {
    $client = XML_RPC2_Client::create($apiUrl);
 
    $conditions = array();
    $conditions[] = array('field'=>'email', 'op'=>'like', 'value'=>'mailchimp');
    $opts = array('match'=>'all', 'conditions'=>$conditions);
 
    $result = $client->campaignSegmentTest($apikey, $listId, $opts );
    echo "SUCCESS! \n";
    echo "Your segment matched ".$result." list members\n";
 
} catch (XML_RPC2_FaultException $e){
	echo "ERROR!!!!\n";
	echo $e->getFaultCode()." : ".$e->getFaultString()."\n";
}
echo "\n";
 
 
?>