Omnistar Mailer API User Guide

1. Introduction

The XML API functionality use to insert subscribers, delete subscribers and get the listing of all subscriber from a mailing list remotely.

2. System Requirements

For using the XML API functionality server must be running PHP 5.1.2 or higher with cURL support.

3. Submitting a Request

For using the XML API functionality you can submit the request through cURL with valid XML format. The XML Path will look similar to the following:

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

For example: http://test.omnistaretools.com/mailer/xml.php

Following are the sample for using the XML API functionality:

a) For Add Subscriber:

<?php
$content = '<?xml version="1.0"?>
<xmlrequest>
<username>admin</username>
<usertoken>21232f297a57a5a743894a0e4a801fc3</usertoken>
<requestmethod>InsertSubscriber</requestmethod>
<emaillist>testing</emaillist>
<details>
<email>abc@xyz.com</email>
<emailformat>HTML</emailformat>
<subscribed>yes</subscribed>
<sendconfirm>no</sendconfirm>
<action>A</action>
<customfields>
<item>
<fieldname>first name</fieldname>
<value>nawal</value>
</item>
<item>
<fieldname>last name</fieldname>
<value>singh</value>
</item>
</customfields>
</details>
</xmlrequest>';

$ch = curl_init("http://test.omnistaretools.com/mailer/xml.php");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, "xml=$content");
$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/>';
}
}
curl_close($ch);
?>

The XML document structure for Adding a subscriber:

xmlrequest (Required) This is the root document tag name.
username (Required) This is the admin user name.
usertoken (Required) This is user token number like password for using the API. You can get it from: http://test.omnistaretools.com/mailer/admin/admin.php?op=edit&id=2
requestmethod (Required) This is the method name for API, For adding the subscriber method name is "InsertSubscriber".
emaillist (Required) This is the email list where you want to add the subscriber.
details (Required) This is the details of subscriber. If you want to add the more then one subscribers at a time just repeat the details tag.
email (Required) This is the email address e.g abc@xyz.com
emailformat (Optional) This is the email formate. It should be HTML or Text
subscribed (Optional) This is the subscription field. It should be yes or no
sendconfirm (Optional) It should be yes or no. If you put yes then send confirmation mail.
action (Optional) It should be A or D.
customfields (Optional) This is the tag for custom field.
item (Optional) If you want to add more than one custom fields just repeat the item tag.
fieldname (Optional) This is custom field name for example "first name"
value (Optional) This is the custom value for example "manish".

If successfully added the subscriber it will return the success message like Status is SUCCESS
Data is abc@xyz.com added successfully.

b) For Delete Subscriber:

<?php
$content = '<?xml version="1.0"?>
<xmlrequest>
<username>admin</username>
<usertoken>21232f297a57a5a743894a0e4a801fc3</usertoken>
<requestmethod>DeleteSubscriber</requestmethod>
<emaillist>testing</emaillist>
<details>
<email>abc@xyz.com</email>
</details>
</xmlrequest>';

The XML document structure for deleting a subscriber:

If successfully delete the subscriber it will return the success message like Status is SUCCESS
Data is abc@xyz.com deleted successfully.

b) For Get Subscriber:

<?php
$content = '<?xml version="1.0"?>
<xmlrequest>
<username>admin</username>
<usertoken>21232f297a57a5a743894a0e4a801fc3</usertoken>
<requestmethod>GetSubscriber</requestmethod>
<emaillist>testing</emaillist>
</xmlrequest>';
$ch = curl_init("http://test.omnistaretools.com/mailer/xml.php");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, "xml=$content");
$result = @curl_exec($ch);
if($result === false) {
echo "Error performing request";
}
else {
header("Content-Type: text/xml");
echo $result;
}
curl_close($ch);
?>

The XML document structure for get the subscriber list:

It will return the all subscribers of the email list in XML formate.