Interspire Email Marketer XML API Documentation

Introduction

1. Requirements
2. Submitting a Request
3. Possible Requests
4. Add Subscriber to a List
5. Broken Response
6. Check Token Works
7. Delete Subscribers
8. Get Custom Field Data
9. Get Lists
10. Get Subscribers
11. Is Contact on List

The Interspire Email Marketer XML API is a remotely accessible service API to allow Interspire Email Marketer users to run many of the Interspire Email Marketer API functions using XML requests.

The Interspire Email Marketer XML API makes it possible to programmatically update and use your system without needing to physically access it. As XML is a general purpose markup language you can use it to communicate between your Java based applications to Interspire Email Marketer’s PHP application base.

For example you could set your system up to automatically update contact lists, create and send email campaigns, gather statistics and many other functions.

Requirements

To make use of the Interspire Email Marketer XML API you will need to be running PHP 5.1.2 or higher.

This document is designed to explain the purpose of these functions and to provide examples of their use.

Submitting a Request

An XML POST request with the details for the license to be generated should be sent to the ‘XML Path’ that you can find in the ‘User Accounts -> Edit User’ section of Interspire Email Marketer under the ‘User Permissions’ tab. Make sure that you have ‘Enable the XML API’ checked and saved. The XML Path will look similar to the following:

http://www.yourdomain.com/IEM/xml.php

The ‘username’ and ‘usertoken’ mentioned in the following examples can be found in this same section under the title of ‘XML Username’ and ‘XML Token’ respectively.

Possible Requests

This section will describe the different functions that can be used by the Interspire Email Marketer XML API.

Add Subscriber to a List

The XML document structure for ‘Adding a subscriber and associated custom details’ request is as follows:/

• xmlrequest (Required)
• username – The user name used to login to the Interspire Email Marketer. (Required)
• usertoken – The unique token assigned to the user account used above. (Required)
• requesttype – The name of the API file in question. (Required)
• requestmethod – The name of the function being called. (Required)
• details (Required)
• emailaddress – The email address of the contact being added. (Required)
• mailinglistid – The list that the contact is located within. (Required)
• confirmed – Sets the confirmation status of the subscriber to confirmed or not (yes or y or true or 1) (Not required, default to unconfirmed)
• format – The format of the email campaigns that this contact prefers to receive (html or h or text or t) (defaults to text)
• customfields
• item
• fieldid – The id of the custom field being added.
• value – The value to be added to this custom field.

Successful Response

Upon submission of a valid ‘add subscriber to list submission a contact will be added to the contact list and the contacts id number returned.

The format is as follows:

• response
• status – The value of the status field will be “SUCCESS” for a successful response.
• data – The contacts ID number.

Sample Request (XML)

The following code sample performs an insertion of the user ‘email@domain.com’ into the mailing list with ID ‘1’ , status set to ‘confirmed’ , format set to ‘html’ and with a custom field set to ‘John Smith’.

<xmlrequest>
	<username>admin</username>
	<usertoken>d467e49b221137215ebdab1ea4e046746de7d0ea</usertoken>
	<requesttype>subscribers</requesttype>
	<requestmethod>AddSubscriberToList</requestmethod>
	<details>
		<emailaddress>email@domain.com</emailaddress>
		<mailinglist>1</mailinglist>
		<format>html</format>
		<confirmed>yes</confirmed>
		<customfields>
			<item>
				<fieldid>1</fieldid>
				<value>John Smith</value>
			</item>
		</customfields>
	</details>
</xmlrequest>

Sample Request (PHP)

The following sample code is written in PHP and makes use of PHP’s CURL functionality to insert the above XML into the application.

<?php
$xml = '<xmlrequest>
	<username>admin</username>
	<usertoken>d467e49b221137215ebdab1ea4e046746de7d0ea</usertoken>
	<requesttype>subscribers</requesttype>
	<requestmethod>AddSubscriberToList</requestmethod>
	<details>
		<emailaddress>email@domain.com</emailaddress>
		<mailinglist>1</mailinglist>
		<format>html</format>
		<confirmed>yes</confirmed>
		<customfields>
			<item>
				<fieldid>1</fieldid>
				<value>John Smith</value>
			</item>
		</customfields>
	</details>
</xmlrequest>
';

$ch = curl_init('http://www.yourdomain.com/IEM/xml.php');
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) {
	echo "Error performing request";
}
else {
	$xml_doc = simplexml_load_string($result);
	echo 'Status is ', $xml_doc->status, '<br/>';
	if ($xml_doc->status == 'SUCCESS') {
		echo 'Data is ', $xml_doc->data, '<br/>';
	} else {
		echo 'Error is ', $xml_doc->errormessage, '<br/>';
	}
}

?>

Broken Response

Notice that the details tag in the example is not closed and no listid is sent for the function to use.

The XML document structure for this example is as follows:

• xmlrequest (Required)
• username – The user name used to login to the Interspire Email Marketer. (Required)
• usertoken – The unique token assigned to the user account used above. (Required)
• requesttype – The name of the API file in question. (Required)
• requestmethod – The name of the function being called. (Required)
• details (Required)

Unsuccessful Response

Upon submission of an erroneous response due to a missing field, or an invalid value the request will fail. A status message will be returned via XML as to why.

In this example you will be presented with the error message:

The format is as follows:

• response
• status – The value of the status field will be “ERROR”.
• errormessage – A textual message explaining why the request failed.

Sample Request (XML)

The following code sample will attempt to post a request to the Get Lists function.

<xmlrequest>
	<username>admin</username>
	<usertoken>78701d1ba2588ea1991f44299b814129658c6947</usertoken>
	<requesttype>lists</requesttype>
	<requestmethod>GetLists</requestmethod>
	</details>
</xmlrequest>

Sample Request (PHP)

The following sample code is written in PHP and makes use of PHP’s CURL functionality to insert the above XML into the application.

<?php
$xml = '<xmlrequest>
	<username>admin</username>
	<usertoken>78701d1ba2588ea1991f44299b814129658c6947</usertoken>
	<requesttype>lists</requesttype>
	<requestmethod>GetLists</requestmethod>
	</details>
</xmlrequest>';

$ch = curl_init('http://www.yourdomain.com/IEM/xml.php');
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) {
	echo "Error performing request";
}
else {
	$xml_doc = simplexml_load_string($result);
	echo 'status is ', $xml_doc->status, '<br/>';
	if ($xml_doc->status == 'SUCCESS') {
		print_r($result);
		} else {
		echo 'Error is ', $xml_doc->errormessage, '<br/>';
	}
}?>

Check Token Works

This example will check to make sure that the token that you are using is a valid token.

Notice that the details tag in the example is still included even though there are no details needed.

• xmlrequest (Required)
• username – The user name used to login to the Interspire Email Marketer. (Required)
• usertoken – The unique token assigned to the user account used above. (Required)
• requesttype – The name of the API file in question. (Required)
• requestmethod – The name of the function being called. (Required)
• details (Required)

Successful Response

Upon submission of a valid ‘check token’ request the XML API will return true.

The format is as follows:

• response
• status – The value of the status field will be “SUCCESS” for a successful response.
• data – This will return ‘1’ for a successful authorization.

Unsuccessful Response

Upon submission of an erroneous response due to a missing field, or an invalid value, the Check Token will fail. A status message will be returned via XML as to why.

In this example you will be presented with the error message:

The format is as follows:

• response
• status – The value of the status field will be “ERROR”.
• errormessage – A textual message explaining why the request failed.

Sample Request (XML)

The following code sample performs an authorization check on the usertoken to make sure that it is a valid token.

<xmlrequest>
	<username>admin</username>
	<usertoken>78701d1ba2588ea1991f44299b814129658c6947</usertoken>
	<requesttype>authentication</requesttype>
	<requestmethod>xmlapitest</requestmethod>
	<details>
	</details>
</xmlrequest>

Sample Request (PHP)

The following sample code is written in PHP and makes use of PHP’s CURL functionality to insert the above XML into the application.

<?php
$xml = '<xmlrequest>
	<username>admin</username>
	<usertoken>78701d1ba2588ea1991f44299b814129658c6947</usertoken>
	<requesttype>authentication</requesttype>
	<requestmethod>xmlapitest</requestmethod>
	<details>
	</details>
</xmlrequest>';

$ch = curl_init('http://www.yourdomain.com/Interspire Email Marketer/xml.php');
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) {
	echo "Error performing request";
}
else {
	$xml_doc = simplexml_load_string($result);
	echo 'status is ', $xml_doc->status, '<br/>';
	if ($xml_doc->status == 'SUCCESS') {
		print_r($result);
		} else {
		echo 'Error is ', $xml_doc->errormessage, '<br/>';
	}
}
?>

Delete Subscriber

This example will delete a contact from your contact list.

• xmlrequest (Required)
• username – The user name used to login to the Interspire Email Marketer. (Required)
• usertoken – The unique token assigned to the user account used above. (Required)
• requesttype – The name of the API file in question. (Required)
• requestmethod – The name of the function being called. (Required)
• details (Required)
• list – The ID of the Contact List that you are wishing to search (Required)
• emailaddress – The email address of the contact that you are attempting to locate (Required)

Successful Response

Upon submission of a valid ‘delete subscriber’ request the XML API will return a status of successful.

The format is as follows:

• response
• status – The value of the status field will be “SUCCESS” for a successful response.
• data
• item - the count of subscribers removed correctly.

Unsuccessful Response

Upon submission of an erroneous response due to a missing field, or an invalid value, the Delete Subscriber will fail. A status message will be returned via XML as to why.

The format is as follows:

• response
• status – The value of the status field will be “ERROR”.
• errormessage – A textual message explaining why the request failed.

Sample Request (XML)

The following code sample will delete the email address listed from the contact list of this ID.

<xmlrequest>
	<username>admin</username>
	<usertoken>78701d1ba2588ea1991f44299b814129658c6947</usertoken>
	<requesttype>subscribers</requesttype>
	<requestmethod>DeleteSubscriber</requestmethod>
	<details>
		<emailaddress>email@domain.com</emailaddress>
		<list>1</list>
	</details>
</xmlrequest>

Sample Request (PHP)

The following sample code is written in PHP and makes use of PHP’s CURL functionality to insert the above XML into the application.

<?php
$xml = '<xmlrequest>
	<username>admin</username>
	<usertoken>78701d1ba2588ea1991f44299b814129658c6947</usertoken>
	<requesttype>subscribers</requesttype>
	<requestmethod>DeleteSubscriber</requestmethod>
	<details>
		<emailaddress>email@domain.com</emailaddress>
		<list>1</list>
	</details>
</xmlrequest>';

$ch = curl_init('http://www.yourdomain.com/IEM/xml.php');
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) {
	echo "Error performing request";
}
else {
	$xml_doc = simplexml_load_string($result);
	echo 'status is ', $xml_doc->status, '<br/>';
	if ($xml_doc->status == 'SUCCESS') {
		print_r($result);
		} else {
		echo 'Error is ', $xml_doc->errormessage, '<br/>';
	}
}
?>

Get Custom Field Data

The XML document structure for retrieving a contact lists custom field data is as follows:

• xmlrequest (Required)
• username – The user name used to login to the Interspire Email Marketer. (Required)
• usertoken – The unique token assigned to the user account used above. (Required)
• requesttype – The name of the API file in question. (Required)
• equestmethod – The name of the function being called. (Required)
• details (Required)
• listids –The ID’s of the contact list that the custom field data is being requested. (Required)

Successful Response

Upon submission of a valid ‘Get Custom Field Data’ submission the custom field data found will be returned in formatted XML.

The format is as follows:

• response
• status – The value of the status field will be “SUCCESS” for a successful response.
• data
• item
• fieldid – The custom fields ID number.
• name – The name of the custom field.
• fieldtype – the type of field (text, number etc.).
• defaultvalue – If you set a default value it will appear here.
• required – If this field is required to be filled in (1 or 0).
• fieldsettings – Serialized version of the custom fields settings

Unsuccessful Response

Upon submission of an erroneous response due to a missing field, or an invalid value the Get Custom Filed Data will fail. A status message will be returned via XML as to why.

The format is as follows:

• response
• status – The value of the status field will be “ERROR”.
• errormessage – A textual message explaining why the request failed.

Sample Request (XML)

The following code sample will draw any information found on the custom fields for the list with the ID of ‘1’.

<xmlrequest>
	<username>admin</username>
	<usertoken>78701d1ba2588ea1991f44299b814129658c6947</usertoken>
	<requesttype>lists</requesttype>
	<requestmethod>GetCustomFields</requestmethod>
	<details>
		<listids>
			1
		</listids>
	</details>
</xmlrequest>

Sample Request (PHP)

The following sample code is written in PHP and makes use of PHP’s CURL functionality to insert the above XML into the application.

<?php
$xml = '<xmlrequest>
	<username>admin</username>
	<usertoken>78701d1ba2588ea1991f44299b814129658c6947</usertoken>
	<requesttype>lists</requesttype>
	<requestmethod>GetCustomFields</requestmethod>
	<details>
		<listids>
			1
		</listids>
	</details>
</xmlrequest>
';

$ch = curl_init('http://www.yourdomain.com/IEM/xml.php');
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) {
	echo "Error performing request";
}
else {
	$xml_doc = simplexml_load_string($result);
	echo 'status is ', $xml_doc->status, '<br/>';
	if ($xml_doc->status == 'SUCCESS') {
		print_r($result);
		} else {
		echo 'Error is ', $xml_doc->errormessage, '<br/>';
	}
}
?>

Get Lists

This example will retrieve a list of all the Contact Lists that are located in Interspire Email Marketer and return formatted XML with the data found.

• xmlrequest (Required)
• username – The user name used to login to the Interspire Email Marketer. (Required)
• usertoken – The unique token assigned to the user account used above. (Required)
• requesttype – The name of the API file in question. (Required)
• requestmethod – The name of the function being called. (Required)
• details (Required)

Successful Response

Upon submission of a valid ‘get lists’ request the XML API will return any data found on the Interspire Email Marketer Contact Lists will be returned in formatted XML.

The format is as follows:

• response
• status – The value of the status field will be “SUCCESS” for a successful response.
• data
• item
• listid – The id of the list.
• name – The name of the list.
• subscribecount – A count of how many subscribed contacts.
• unsubscribecount – A count of how many unsubscribed contacts.
• autorespondercount – A count of how many autoresponders are linked to the Contact List.

Unsuccessful Response

Upon submission of an erroneous response due to a missing field, or an invalid value, the Get Lists will fail. A status message will be returned via XML as to why.

In this example you will be presented with the error message:

The format is as follows:

• response
• status – The value of the status field will be “ERROR”.
• errormessage – A textual message explaining why the request failed.

Sample Request (XML)

The following code sample performs a request to return all the Contact Lists located within Interspire Email Marketer.

<xmlrequest>
	<username>admin</username>
	<usertoken>78701d1ba2588ea1991f44299b814129658c6947</usertoken>
	<requesttype>user</requesttype>
	<requestmethod>GetLists</requestmethod>
	<details>
	</details>
</xmlrequest>

Sample Request (PHP)

The following sample code is written in PHP and makes use of PHP’s CURL functionality to insert the above XML into the application.

<?php
$xml = '<xmlrequest>
	<username>admin</username>
	<usertoken>78701d1ba2588ea1991f44299b814129658c6947</usertoken>
	<requesttype>user</requesttype>
	<requestmethod>GetLists</requestmethod>
	<details>
	</details>
</xmlrequest>';

$ch = curl_init('http://www.yourdomain.com/IEM/xml.php');
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) {
	echo "Error performing request";
}
else {
	$xml_doc = simplexml_load_string($result);
	echo 'status is ', $xml_doc->status, '<br/>';
	if ($xml_doc->status == 'SUCCESS') {
		print_r($result);
		} else {
		echo 'Error is ', $xml_doc->errormessage, '<br/>';
	}
}
?>

Get Subscribers

This example will retrieve a count of the amount of Contacts on the list in question as well as a list of all the Contacts that are located in that list and return formatted XML with the data found.

• xmlrequest (Required)
• username – The user name used to login to the Interspire Email Marketer. (Required)
• usertoken – The unique token assigned to the user account used above. (Required)
• requesttype – The name of the API file in question. (Required)
• requestmethod – The name of the function being called. (Required)
• details (Required)
• searchinfo
• List – The ID of the Contact List that you are wishing to search (Required)
• Email – The email address of the contact that you are attempting to locate (Required)

Successful Response

Upon submission of a valid ‘get subscribers’ request the XML API will return a count of the amount of Contacts on the list in question along with a list of those contact email addresses in formatted XML.

The format is as follows:

• response
• status – The value of the status field will be “SUCCESS” for a successful response.
• data
• count – A count of the amount of subscribers.
• subscriberlist – A list of the subscribers email addresses.

Unsuccessful Response

Upon submission of an erroneous response due to a missing field, or an invalid value, the Get Subscribers will fail. A status message will be returned via XML as to why.

The format is as follows:

• response
• status – The value of the status field will be “ERROR”.
• errormessage – A textual message explaining why the request failed.

Sample Request (XML)

The following code sample performs a check on the Contact List with ID ‘1’ for all email addresses that contain the information ‘@yourdomain.com’.

<xmlrequest>
	<username>admin</username>
	<usertoken>78701d1ba2588ea1991f44299b814129658c6947</usertoken>
	<requesttype>subscribers</requesttype>
	<requestmethod>GetSubscribers</requestmethod>
	<details>
		<searchinfo>
			<List>1</List>
			<Email>@yourdomain.com</Email>
		</searchinfo>
	</details>
</xmlrequest>

Sample Request (PHP)

The following sample code is written in PHP and makes use of PHP’s CURL functionality to insert the above XML into the application.

<?php
$xml = '<xmlrequest>
	<username>admin</username>
	<usertoken>78701d1ba2588ea1991f44299b814129658c6947</usertoken>
	<requesttype>subscribers</requesttype>
	<requestmethod>GetSubscribers</requestmethod>
	<details>
		<searchinfo>
			<List>1</List>
			<Email>@yourdomain.com</Email>
		</searchinfo>
	</details>
</xmlrequest>';

$ch = curl_init('http://www.yourdomain.com/IEM/xml.php');
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) {
	echo "Error performing request";
}
else {
	$xml_doc = simplexml_load_string($result);
	echo 'status is ', $xml_doc->status, '<br/>';
	if ($xml_doc->status == 'SUCCESS') {
		print_r($result);
		} else {
		echo 'Error is ', $xml_doc->errormessage, '<br/>';
	}
}
?>

Is Contact on List

This example will check to see if a particular Contact is located on a particular Contact List.

• xmlrequest (Required)
• username – The user name used to login to the Interspire Email Marketer. (Required)
• usertoken – The unique token assigned to the user account used above. (Required)
• requesttype – The name of the API file in question. (Required)
• requestmethod – The name of the function being called. (Required)
• details (Required)
• Email – The email address of the Contact you are searching for (Required)
• List – The ID of the Contact List you are wanting to search (Required)

Successful Response

Upon submission of a valid ‘is contact on list’ request the XML API will return true if it locates the contact and will return nothing if not.

The format is as follows:

• response
• status – The value of the status field will be “SUCCESS” for a successful response.
• data – Will return ‘1’ if contact is located.

Unsuccessful Response

Upon submission of an erroneous response due to a missing field, or an invalid value, the Is Contact on List will fail. A status message will be returned via XML as to why.

The format is as follows:

• response
• status – The value of the status field will be “ERROR”.
• errormessage – A textual message explaining why the request failed.

Sample Request (XML)

The following code sample performs a check on a contact list to see if a particular contact is listed on it.

<xmlrequest>  
      <username>admin</username>  
       <usertoken>78701d1ba2588ea1991f44299b814129658c6947</usertoken>  
	<requesttype>subscribers</requesttype>
        <requestmethod>IsSubscriberOnList</requestmethod>
	<details>
		<Email>email@yourdomain.com</Email>
		<List>1</List>
	</details>
</xmlrequest>

Sample Request (PHP)

The following sample code is written in PHP and makes use of PHP’s CURL functionality to insert the above XML into the application.

<?php
$xml = ' <requesttype>subscribers</requesttype>
	<requestmethod>IsSubscriberOnList</requestmethod>
	<details>
		<Email>email@yourdomain.com</Email>
		<List>1</List>
	</details>
</xmlrequest>';

$ch = curl_init('http://www.yourdomain.com/IEM/xml.php');
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) {
	echo "Error performing request";
}
else {
	$xml_doc = simplexml_load_string($result);
	echo 'status is ', $xml_doc->status, '<br/>';
	if ($xml_doc->status == 'SUCCESS') {
		print_r($result);
		} else {
		echo 'Error is ', $xml_doc->errormessage, '<br/>';
	}
}
?>