XML API Documentation

Introduction

The MyEmailProgram XML API is a remotely accessible service API to allow MyEmailProgram users to run many of the API functions using XML requests. The 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 MyEmailProgram’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.

Submitting a Request

An XML POST request with the details for the license to be generated should be sent to the ‘XML Path,’https://www.myemailprogram.com/app/xml.php’. The ‘username’ is the username you use to login to MyEmailProgram. The ‘usertoken’ mentioned in the following examples can be requested by submitting a ticket via our help desk. In the rest of this documentation the examples will be ‘XML Username’ and ‘XML Token’ respectively.

Possible Requests

This section will describe the different functions that can be used by the 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 MyEmailProgram. (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 protected]’ 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 protected]</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 protected]</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(‘https://www.myemailprogram.com/app/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, ‘ ’;
if ($xml_doc->status == ‘SUCCESS’) {
echo ‘Data is ‘, $xml_doc->data, ‘ ’;
} else {
echo ‘Error is ‘, $xml_doc->errormessage, ‘ ’;
}
}

Broken Response
This example will demonstrate an error message that is returned when a bad request is made. 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. (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 XML you provided is not valid. Please check your xml document and try again.’

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.

$ch = curl_init(‘https://www.myemailprogram.com/app/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, ‘ ’;
if ($xml_doc->status == ‘SUCCESS’) {
print_r($result);
} else {
echo ‘Error is ‘, $xml_doc->errormessage, ‘ ’;
}
}?>

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.

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:

‘Invalid details’

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(‘https://www.myemailprogram.com/app/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, ‘ ’;
if ($xml_doc->status == ‘SUCCESS’) {
print_r($result);
} else {
echo ‘Error is ‘, $xml_doc->errormessage, ‘ ’;
}
}
?>

Delete Subscriber

This example will delete a contact from your contact list.

• xmlrequest (Required)
• username – The user name. (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 protected]</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 protected]</emailaddress>
<list>1</list>
</details>
</xmlrequest>’;

$ch = curl_init(‘https://www.myemailprogram.com/app/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, ‘ ’;
if ($xml_doc->status == ‘SUCCESS’) {
print_r($result);
} else {
echo ‘Error is ‘, $xml_doc->errormessage, ‘ ’;
}
}
?>

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. (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’.

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(‘https://www.myemailprogram.com/app/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, ‘ ’;
if ($xml_doc->status == ‘SUCCESS’) {
print_r($result);
} else {
echo ‘Error is ‘, $xml_doc->errormessage, ‘ ’;
}
}
?>

Get Lists

This example will retrieve a list of all the Contact Lists that are located in MyEmailProgram and return formatted XML with the data found. Notice that the details tag in the example is still included even though there are no details needed.

Successful Response

Upon submission of a valid ‘get lists’ request the XML API will return any data found on the 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:

‘Invalid details’

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.

<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(‘https://www.myemailprogram.com/app/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, ‘ ’;
if ($xml_doc->status == ‘SUCCESS’) {
print_r($result);
} else {
echo ‘Error is ‘, $xml_doc->errormessage, ‘ ’;
}
}
?>

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. (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(‘https://www.myemailprogram.com/app/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, ‘ ’;
if ($xml_doc->status == ‘SUCCESS’) {
print_r($result);
} else {
echo ‘Error is ‘, $xml_doc->errormessage, ‘ ’;
}
}
?>

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. (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>
<emailaddress>[email protected]</emailaddress>
<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>subscribers</requesttype>
<requestmethod>IsSubscriberOnList</requestmethod>
<details>
<emailaddress>[email protected]</emailaddress>
<listids>1</listids>
</details>
</xmlrequest>’;

$ch = curl_init(‘https://www.myemailprogram.com/app/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, ‘ ’;
if ($xml_doc->status == ‘SUCCESS’) {
print_r($result);
} else {
echo ‘Error is ‘, $xml_doc->errormessage, ‘ ’;
}
}
?>

If you have any questions or problems regarding the API please submit a ticket through the help desk.

XML API Documentation

Introduction

Submitting a Request

Possible Requests

Add Subscriber to a List

Check Token Works

Delete Subscriber

Get Custom Field Data

Get Lists

Get Subscribers

Is Contact on List

Additional Resources

Integrations

About Us