Introduction
Email Marketing MFORMULA MAIL API is a remote access to the API service to allow users of MFORMULA MAIL Email Marketing to perform many functions using XML requests.
Email Marketing MFORMULA MAIL XML API makes it possible to programmatically update and use your system without the need to physically access it. An XML is a general language with the purpose to communicate between your application and Email Marketing MFORMULA MAIL.
For example, you can configure your system to automatically update contact lists, create and send email campaigns, collect statistics, and many other functions.

Requirements
To make use of the MFORMULA MAIL XML API Email Marketing you need to have PHP 5.1.2 or higher.
This document is intended to explain the purpose of these functions and to provide examples of their use.

Submit an Order
An XML POST request with the details for the license to be generated should be sent to the 'XML Path'
Which you can find in the 'User Accounts -> User Edit' section of the Email Marketing MFORMULA MAIL under the 'User
Permissions' tab. Make sure that you've enabled the 'Enable the XML API' test and save it. The XML Path will look similar:
http://www.mformulamail.com/webmarketingpt/xml.php
or
http://www.mformulamail.com/webmarketingen/xml.php
The 'username' and 'usertoken' mentioned in the following examples can be found in this same section
Under the title 'XML Username' and 'XML Token' respectively.

Eventual Requests
This section describes the different functions that can be used by Email Marketing MFORMULA MAIL XML
Instructions in English only

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 Email Marketing MFORMULA MAIL. (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 ‘Name LastName’.

<xmlrequest>
<username>YOURUSERNAME</username>
<usertoken>YOURTOKEN</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>Name LastName</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>YOURUSERNAME</username>
<usertoken>YOURTOKEN</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>Name LastName</value>
</item>
</customfields>
</details>
</xmlrequest>
';

$ch = curl_init('http://www.mformulamail.com/webmarketingen/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

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 used to login to the Email Marketing MFORMULA MAIL. (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>YOURUSERNAME</username>
<usertoken>YOURTOKEN</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>YOURUSERNAME</username>
<usertoken>YOURTOKEN</usertoken>
<requesttype>lists</requesttype>
<requestmethod>GetLists</requestmethod>
</details>
</xmlrequest>';

$ch = curl_init('http://www.mformulamail.com/webmarketingen/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 Email Marketing MFORMULA MAIL. (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:

‘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>YOURUSERNAME</username>
<usertoken>YOURTOKEN</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>YOURUSERNAME</username>
<usertoken>YOURTOKEN</usertoken>
<requesttype>authentication</requesttype>
<requestmethod>xmlapitest</requestmethod>
<details>
</details>
</xmlrequest>';

$ch = curl_init('http://www.yourdomain.com/Email Marketing MFORMULA MAIL/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 Email Marketing MFORMULA MAIL. (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>YOURUSERNAME</username>
<usertoken>YOURTOKEN</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>YOURUSERNAME</username>
<usertoken>YOURTOKEN</usertoken>
<requesttype>subscribers</requesttype>
<requestmethod>DeleteSubscriber</requestmethod>
<details>
<emailaddress>email@domain.com</emailaddress>
<list>1</list>
</details>
</xmlrequest>';

$ch = curl_init('http://www.mformulamail.com/webmarketingen/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 Email Marketing MFORMULA MAIL. (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>YOURUSERNAME</username>
<usertoken>YOURTOKEN</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>YOURUSERNAME</username>
<usertoken>YOURTOKEN</usertoken>
<requesttype>lists</requesttype>
<requestmethod>GetCustomFields</requestmethod>
<details>
<listids>1</listids>
</details>
</xmlrequest>
';
$ch = curl_init('http://www.mformulamail.com/webmarketingen/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 Email Marketing MFORMULA MAIL 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.

• xmlrequest (Required)
• username – The user name used to login to the Email Marketing MFORMULA MAIL. (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 Email Marketing MFORMULA MAIL 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 located within Email Marketing MFORMULA MAIL.

<xmlrequest>
<username>YOURUSERNAME</username>
<usertoken>YOURTOKEN</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>YOURUSERNAME</username>
<usertoken>YOURTOKEN</usertoken>
<requesttype>user</requesttype>
<requestmethod>GetLists</requestmethod>
<details>
</details>
</xmlrequest>';

$ch = curl_init('http://www.mformulamail.com/webmarketingen/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 Email Marketing MFORMULA MAIL. (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>YOURUSERNAME</username>
<usertoken>YOURTOKEN</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>YOURUSERNAME</username>
<usertoken>YOURTOKEN</usertoken>
<requesttype>subscribers</requesttype>
<requestmethod>GetSubscribers</requestmethod>
<details>
<searchinfo>
<List>1</List>
<Email>@yourdomain.com</Email>
</searchinfo>
</details>
</xmlrequest>';

$ch = curl_init('http://www.mformulamail.com/webmarketingen/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 Email Marketing MFORMULA MAIL. (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>YOURUSERNAME</username>
<usertoken>YOURTOKEN</usertoken>
<requesttype>subscribers</requesttype>
<requestmethod>IsSubscriberOnList</requestmethod>
<details>
<emailaddress>email@yourdomain.com</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>YOURUSERNAME</username>
<usertoken>YOURTOKEN</usertoken>
<requesttype>subscribers</requesttype>
<requestmethod>IsSubscriberOnList</requestmethod>
<details>
<emailaddress>email@yourdomain.com</emailaddress>
<listids>1</listids>
</details>
</xmlrequest>';

$ch = curl_init('http://www.mformulamail.com/webmarketingen/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/>';
}
}
?>