API 101

To work with our REST API, it helps to understand a few basics.

A REST API is a "REpresentational State Transfer Application Programming Interface", a very long-winded way of describing a Web-based system for accessing the capabilities of someone else's software.

REST APIs work in a client-server model. A client (that's your code) makes a call to a server (that's us) to make something happen.

The core of a REST API is a call to a Web address that either returns some desired information, or causes some action to happen. REST APIs use the HTTP protocol of the Web to control the system they're built on. You'll make HTTP requests to click2mail.com in order to drive the powerful engine we've built for you.

A REST API consists of a set of "endpoints" or "resources", which can be thought of as the commands you are issuing to the API. For example, the following "credit" endpoint instructs the staging environment to return the amount of credit a customer has on their account:

https://stage-rest.click2mail.com/molpro/credit

As part of the call, you would also need to include authentication information so the server would know who you are and therefore which account to return information about. It will then return an HTTP response code and formatted information, in this case as XML text:

RESPONSE [200]
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<credit>
    <balance>0.0</balance>
    <allowNegative>false</allowNegative>
</credit>

In this example, the server returned a response code of 200 (OK), which means it was successful! The XML information shows that the balance on the account is $0.00, and that this account is not allowed to go negative.

Each of these endpoints can have parameters that control exactly what you want that request to do. HTTP has several "methods" it uses to tell the server what the client wants. We're mostly interested in these four:

As you build out your application, you'll make calls to various API endpoints, using the methods shown above, in order to tell the Click2Mail system exactly what you want it to do. You'll use the information that's passed back to determine if your request worked and get other information about what happened. Using this simple model, you can drive powerful mail workflow processes. Let's get started!