Email Marketer XML API usage and examples.
Email Marketer’s API can be invoked by sending XML requests. The API files are found in the /emailmarketer/admin/functions/api/ directory. Each XML request requires a username, user token, request type, request method, and details. The API file containing the method you want to invoke is the request type, the method itself is the request method, and the method’s parameters are the details. Email Marketer’s source code is commented in a format that allows scripts like phpDocumentor to generate documentation. Each class and method contains a detailed description. You can download phpDocumentor for free at phpdoc.org. Following is an example of a XML API request sent through PHP with cURL. There are also several example scripts attached at the bottom for your reference.
<?php
//searchinfo
// must contain a list id: <List>1</List> or <List>any</List>
// You can also filter the search by Status, Confirmed, CustomFields, Subscriber, Email, Format, Newsletter, Link, etc
// I took the list above from the function GenerateSubscriberSubQuery line 2199 of /api/subscribers.php
$xml = "
<xmlrequest>
<username>YOUR_USERNAME_HERE</username>
<usertoken>YOUR_TOKEN_HERE</usertoken>
<requesttype>subscribers</requesttype>
<requestmethod>GetSubscribers</requestmethod>
<details>
<searchinfo>
<List>1</List>
<Status>a</Status>
<Confirmed>1</Confirmed>
</searchinfo>
</details>
</xmlrequest>
";
$ch = curl_init('http://YOUREMAILMARKETER.com/xml.php'); //change to the path to your xml.php file
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $xml);
$result = @curl_exec($ch);
if($result != false) {
$xml_doc = simplexml_load_string($result);
if($xml_doc != false){
echo "Result: <br />";
var_dump($xml_doc);
echo "<br /><br />";
}
} else {
echo "Error performing request: <br />";
var_dump($result);
echo "<br /><br />";
}
?>Can I use my existing user database with Interspire Email Marketer?
Yes, you can create PHP scripts which call the IEM functions and classes, or you can use the XML API. Using the XML API is usually going to be the preferred solution.
On the other hand, in some cases, it may be more effective to simply write a PHP script that calls Email Marketer’s built in classes and functions. For example, you could write a script like this to add a user to a contact list:
$installDir = 'your IEM install directory';
$emailAddress = 'your email address to add to the contact list';
$contactListId = 'your contact list ID';
defined('IEM_NO_CONTROLLER') or define('IEM_NO_CONTROLLER',true); //bypass login prompt
require($installDir.'/admin/index.php'); //pull in base required classes
require($installDir.'/admin/functions/api/subscribers.php'); //pull in Subscribers API
$subscriber_api = &new Subscribers_API();
$subscriber_api->AddToList($emailAddress, $contactListId);
?>Now, to make this really useful, you might build a loop around it to import a batch of contacts from your existing user database, but this should give you a good picture of the basic concept.
Can I create an Email Campaign with the API?
You can easily create email campaigns with the Email Marketer API. A sample script is attached which shows how to set up and call the Email Marketer API, and then create a campaign with it. You can use any of the files in the /admin/functions/ and /admin/functions/api/ directories for more examples on how to use the API functions.
Is there a way to add an email to a Suppression List via the API?
You can add an email or a list of emails to the global or list-specific supression list using the XML API or the PHP API (use the attached PHP script as reference)
XML API.
<xmlrequest>
<username>XML API username</username>
<usertoken>XML API token</usertoken>
<requesttype>subscribers</requesttype>
<requestmethod>AddBannedSubscriber</requestmethod>
<details>
<emailaddress>email address that you want to be banned/suppressed</emailaddress>
<listid>id of the list you want the email to be suppressed from or 'global' for all lists</listid>
</details>
</xmlrequest>PHP API.
<?php
if (!defined('IEM_NO_CONTROLLER')) {
define('IEM_NO_CONTROLLER', true);
}
require_once 'admin/index.php'; //Change to location of your /emailmarketer/admin/index.php file
require_once(SENDSTUDIO_FUNCTION_DIRECTORY . '/sendstudio_functions.php');
$SendstudioFunctions = new Sendstudio_Functions();
$listid = "global"; // id of the list you want to suppress from or "global" for all lists
$emailaddresses = "[email protected]"; // comma separated list of email addresses
$bannedlist = explode(",",$emailaddresses);
if (empty($bannedlist)) {
die("You haven't supplied any emails");
}
$subscriber_api = $SendstudioFunctions->GetApi('Subscribers');
$success = array();
$fail = array('addresses' => array(), 'messages' => array());
$subscriber_api->Db->StartTransaction();
foreach ($bannedlist as $pos => $emailaddress) {
// skip empty ones.
if (!$emailaddress) {
continue;
}
if (!stristr($emailaddress, "@")){
$fail['addresses'][] = $emailaddress;
$fail['messages'][] = "Suppressions must contain the '@' symbol";
continue;
}
list($status, $msg) = $subscriber_api->AddBannedSubscriber($emailaddress, $listid);
if (!$status) {
$fail['addresses'][] = $emailaddress;
$fail['messages'][] = $msg;
continue;
}
$success[] = $emailaddress;
}
$subscriber_api->Db->CommitTransaction();
$report = '';
if (!empty($success)) {
if (sizeof($success) > 1) {
$report .= sizeof($success).' email addresses were successfully added to your suppression email list.<br/>';
} else {
$report .= '1 email address has been suppressed successfully<br/>';
}
}
if (!empty($fail['addresses'])) {
$errormsg .= "The following addresses weren't added to the suppression email list:";
foreach ($fail['addresses'] as $pos => $email) {
$errormsg .= '<br/>' . $email . ' (' . $fail['messages'][$pos] . ')';
}
$report .= $errormsg;
}
echo $report;
?>Can I unsubscribe contacts via the API?
You can easily unsubscribe contacts using the XML API or the PHP API (see the attached example PHP script for more details)
XML API.
<xmlrequest>
<username>XML API username</username>
<usertoken>XML API token</usertoken>
<requesttype>subscribers</requesttype>
<requestmethod>UnsubscribeSubscriber</requestmethod>
<details>
<emailaddress>email address of the subscriber</emailaddress>
<listid>id of the list the subscriber belongs to</listid>
<subscriberid>id of the subscriber</subscriberid>
</details>
</xmlrequest>PHP API.
<?php
if (!defined('IEM_NO_CONTROLLER')) {
define('IEM_NO_CONTROLLER', true);
}
require_once 'admin/index.php'; //Change to location of your /emailmarketer/admin/index.php file
require_once(SENDSTUDIO_FUNCTION_DIRECTORY . '/sendstudio_functions.php');
$emailaddress = ''; // email of the contact that you want unsubscribed
$listid = ''; // id of the contat list this subscriber should be unsubscribed from
$subscriberid = ''; // id of the subscriber
$SendstudioFunctions = new Sendstudio_Functions();
$subscriber_api = $SendstudioFunctions->GetApi('Subscribers');
$result = $subscriber_api->UnsubscribeSubscriber($emailaddress,$listid,$subscriberid);
if ($result[0])
{
echo "$emailaddress was successfully unsubscribed.";
}
else
{
echo "Error: ".$result[1];
}
?>