Using the JangoMail API

The JangoMail API is a remotely accessible web service that can be interacted with through several methods, all of which are available across the Internet. It allows you to get data into and out of your JangoMail account programmatically and without visiting the main JangoMail website.

What data can I access using the JangoMail Web Service?

The JangoMail Web Service allows you to:

• Manage bounces and unsubscribes
• Manage lists and the email addresses contained within them
• Trigger mass emails
• Retrieve reporting data
• And much, much more! 

All of these functions can be accessed programmatically from a variety of remote platforms and through a variety of methods. A full listing of methods can be found at https://api.jangomail.com/.

Why would I use the web service?

You would use this feature if you need to remotely access data in your JangoMail account using an application running on your own desktop or server.

Here are some scenarios where the JangoMail Web Service could streamline and automate daily business tasks:

• A customer indicates on your website that they wish to unsubscribe from future mailings. Your website can add the specified email address to your JangoMail unsubscribe list immediately and automatically.
• On the first of the month you want to trigger a mass email to distribute last month’s sales activity to your sales force.
• A customer registers on your website and his information is stored in your company's CRM system. Your website can also automatically add the new user and his information to a JangoMail list.

How can I access the JangoMail Web Service?

The JangoMail Web Service is accessible via HTTP GET, HTTP POST, and Simple Object Access Protocol (SOAP) at http://api.jangomail.com or securely at https://api.jangomail.com. For a complete list of methods and their parameters see the class reference below. 

To access JangoMail API, use your account's master login (username and password) or create an API Token (API Key).

To create an API Token,  you can call:

CreateAPIToken. This requires Username, Password, and Description. Description is for your own purposes to denote what the token is for. Again, it can be blank, but it must be included. The response will return a GUID which is the API token for the account.
DeleteAPIToken. This requires Username, Password, and Token. If the token exists, it will be deleted.
Note: We have no way to recovering lost tokens and we do not display them in the UI. If you lose them, they are lost and need to be recreated.

To make API calls: Leave the Username blank (but still include the parameter in the call, or it will fail) and include the token in the Password field.

How do I format a request to the JangoMail Web Service?

Accessing via HTTP GET:

Methods can be accessed by performing an HTTP GET request to a URL in this format:

http://api.jangomail.com/api.asmx/[MethodName]?Username=[Username]&Password=[Password] &[Additional_Parameter1]=[Value1]&[Additional_Parameter2]=[Value2]&…

where MethodName is the function you want to perform, Username is your JangoMail account username, Password is your JangoMail account password, and Additional_Parameter1/Value1, Additional_Parameter2/Value2, etc. are additional parameters required by the method.

For example, the AddBounce method requires an email address as an additional parameter. GET requests can be performed using your web browser or through any platform that can send an HTTP GET request such as ASP, PERL or Java.

Responses from an HTTP GET or HTTP Post are in the following format:

Response_Code is the status code, Response_Description is the descriptive name for this response code, and Additional_Response_Line1, Additional_Response_Line2, etc. are new line delimited additional text values. For example, a call to the method GetUnsubsubscribeList returns a response in this format: 

Code example in ASP/VBScript to add an email address to your unsubscribe list via HTTP GET:

Same example in PERL:

Accessing via HTTP POST:

Methods can be accessed by performing an HTTP POST request to a URL in this format:

http://api.jangomail.com/api.asmx/[MethodName] and posting method parameters in this format:

Username=[Username]&Password=[Password] &[Additional_Parameter1]=[Value1]&
&[Additional_Parameter2]=[Value2]&…

where MethodName is the function you want to perform, Username is your JangoMail account username, Password is your JangoMail account password, and Additional_Parameter1/Value1, Additional_Parameter2/Value2, etc. are additional parameters required by the method.

For example, the AddBounce method requires an email address as an additional parameter. POST requests can performed using your web browser or through any platform that can send an HTTP POST request such as ASP, PERL or Java.

Responses to a POST request are in identical format to the response from a GET request.

Code example in ASP/VBScript to add an email address to your unsubscribe list via HTTP POST:

Same example in PERL: 

Accessing via Simple Object Access Protocol: 

The JangoMail Web Service is also fully compliant with the Simple Object Access Protocol as described by the World Wide Web Consortium (W3C) and is the preferred method for accessing JangoMail data. SOAP is a simple XML based protocol to let applications exchange information over HTTP. The main advantages of SOAP compared to other standards are:

• SOAP is designed to communicate via Internet
• SOAP is platform independent
• SOAP is language independent
• SOAP is based on XML
• SOAP is simple and extensible
• SOAP allows you to get around firewalls
• SOAP will be developed as a W3C standard 

For more information on SOAP please refer to:

• http://www.w3schools.com/soap/soap_intro.asp
• http://www.cs.fsu.edu/~engelen/soap.html (gSOAP, C++ toolkit)
• http://www.perl.com/pub/a/2001/01/soap.html (Perl SOAP module)
• http://www.w3.org/TR/soap/ (W3C specification) 

The JangoMail Web Service can be accessed at http://api.jangomail.com/api.asmx or securely at https://api.jangomail.com/api.asmx.

If you are using Visual Studio .NET, the associated classes for calling the SOAP interface can be generated manually using wsdl.exe with the following call:

wsdl.exe /language:cs /out:JangoMailServiceProxy.csc
http://api.jangomail.com/api.asmx?WSDL

This will create JangoMailServiceProxy.csc which you can include in a Visual Studio project, or you can generate a DLL to use with an ASP.NET application with the following command:

csc.exe /t:library /out:JangoMailServiceProxy.dll
JangoMailServiceProxy.csc

This will compile JangoMailServiceProxy.csc to JangoMailServiceProxy.dll which you can reference in a Visual Studio project, or place in your webserver’s /bin directory for use with an ASP.NET application. Sample call from a C# application:

SOAP requests can also be sent manually if formatted correctly and the correct HTTP headers are sent with the request. A SOAP request to the AddUnsubscribe method has the following format:

Here is a code sample in classic ASP that can create and submit a SOAP request:

JangoMail Web Service Function Reference 

For a complete reference to the web service’s methods and signatures, you can use this download. 

JangoMail Web Service Exception Handling

If a particular method fails, the JangoMail Web Service will throw an exception instead
of returning the method’s actual return type. For example, an exception will be thrown
if invalid parameters are passed into a method, such as an invalid username/password
combination. An exception might also be thrown if there is an internal system error.
We recommend writing your code to catch these exceptions in case they occur. For
example, in C#, this can be accomplished using try/catch blocks. Here is an example
using the AddUnsubscribe method.

In this code sample, if the username/password combination of “test” or “pass” is invalid,
then the execution of the code will be passed to the catch block, and an appropriate
error will be written to the console. Similarly if the email address is an invalid email
address, the catch block would write a friendly error message to the console. If the
method is successful, then the ResultString variable is set to “0\nSUCCESS” and the code
would write out the sentence “The unsubscribe operation was successful.” to the
console.

All methods will only return their true return type if the method executes successfully
and all input parameters are valid. If a method is unable to execute successfully for any
reason, an exception is thrown instead of returning the expected object type.

Here’s an example where the API is called using an HTTP POST rather than SOAP in
Visual Basic:

If the username/password combination is invalid, then RetVal would be set to:

Web Service Exception LoginFaledException: Username and password do not match.

If the method does execute successfully, then RetVal would be set to:

<?xml version="1.0" encoding="utf-8"?>
<string xmlns="http://api.jangomail.com/">0
SUCCESS</string>