FlowMail API

As a new feature added to FlowMail 2.0 there is a publicly-accessible XML-based API for web developers to query and update flowmail. The following is a technical description of this API that may be helpful for any developer who wishes to update FlowMail from a website or client application.

Overview

The HTTP address of the API is: http://www.flowmail.net/interface.asp

Any programming framework / language will be able to interact with this interface as long as it supports POST/GET requests and XML parsing. For example, in javascript, the XMLHttpRequest object (or the Microsoft.XMLHTTP object) is capable of sending and recieving HTTP data from a web-page. (*see notes below for JavaScript security restrictions)

An example HTTP GET Request that could be sent to the FlowMail API is as follows:

http://www.flowmail.net/interface.asp?xml=[place your xml code here]

 Example XML code to create a new Address List would look like this:

<?xml version="1.0" encoding="iso-8859-1"?>
<flowmail>
    <authenticate>
        <un>MyUsername</un>
        <pw>520410ded6955e31b3b09683de22b18f</pw>
        <id>01234567</id>
        <dt>04/01/2008 16:32:11</dt>
    </authenticate>
    <command action="address_list_create">
        <name>Test List</name>
    </command>
</flowmail>

Example XML Code to insert contacts into a specific Address List would look like this:

<?xml version="1.0" encoding="iso-8859-1"?>
<flowmail>
    <authenticate>
        <un>MyUsername</un>
        <pw>520410ded6955e31b3b09683de22b18f</pw>
        <id>01234567</id>
        <dt>04/01/2008 16:32:12</dt>
    </authenticate>
    <command action="contact_insert">
        <contact>
            <f_name>John</f_name>
            <l_name>Doe</l_name>
            <email>jdoe@myemail.com</email>
        </contact>
        <contact>
            <f_name>Jane</f_name>
            <l_name>Doe</l_name>
            <email>jane.doe@myemail.com</email>
        </contact>
    </command>
</flowmail>

Authentication

There are four fields required for authentication:

• <id> : Unique Request ID
• <dt> : Date/Time of Request
• <un> : FlowMail Username
• <pw> : Password-based MD5 Hash

FlowMail Username is your regular username that you login to FlowMail with normally.

Each request you send must have a UNIQUE Request ID. This ID can be any string of numbers or letters of your choosing but, again, it must be globally unique. This ensures the same request cannot be submitted more than once.

The Date/Time of the request must be a string containing the current UTC (GMT) date and time. This can be in any of several acceptable formats including: MM/DD/YYYY HH:MM:SS in 24-hour time or M/D/YYYY H:M:S PM. Remember this MUST be the current UTC date/time.

The MD5 Hash must be a 32-character lowercase hexidecimal string that is calculated from concatinating the Request ID string, the Date/Time string, and the MD5 hash of your FlowMail password.

Example: MD5(strRequestID + strDateTime + MD5(strPassword))

This means that the hash function is called TWICE. Once to hash the user's password and once again to hash the entire string.

If you do not understand what an MD5 hash is, or do not know how to calculate this in your programming language, look it up on the internet. An MD5 hash algorithm/function is available for every major programming language and built into most database interfaces.

 Commands

The commands currently available in the FlowMail API are:

• address_list_create
• address_list_query
• contact_insert

The address_list_create command is the simplest. It takes only one parameter: name

The contact_insert command takes one XML attribute: authcode="012345" which contains the AuthCode of the address list into which you wish to insert the contact(s) and it also takes one or more contacts as parameter(s) which are formatted in the following way:

<contact>
    <f_name>John</f_name>
    <l_name>Doe</l_name>
    <email>jdoe@myemail.com</email>
</contact>

Each Command Returns a result and/or an error in XML format as follows:

<flowmail>
    <result>9 Contacts Added</result>
</flowmail>

-OR-

<flowmail>
    <error>Authentication Failed</error>
</flowmail>

The address_list_query command takes no parameters, but returns an XML DataSet in the following format:

<flowmail>
    <data_set>
        <record>
            <authcode>012345</authcode>
            <cat_name>Address List 1</cat_name>
        </record>
        <record>
            <authcode>543210</authcode>
            <cat_name>Address List 2</cat_name>
        </record>
    </data_set>
    <result>Query Returned 2 Records</result>
</flowmail>

There will likely be more functionality added to the FlowMail API in the future, but the format for sending commands and receiving results should stay the same. 

 Misc Notes

• JavaScript: Most modern browsers have cross-site scripting restrictions that, for security reasons, restrict you from directly making XMLHttpRequest calls to other domains. In cases such as this, you can still use the FlowMail API but you must use a Server-Side Proxy of some kind on your own site to pass XML between your client and FlowMail.
•  Keep in mind that XML is CASE SENSATIVE
• Also, certain characters like an ampersand (&) are not valid in xml unless encoded (similar to HTML encoding) as &amp; (a function to HTML-encode strings is present in most web languages)