IntroductionWelcome to the Apsis API. In this tutorial we will give you a quick overview of how to get started by walking you through how to build a simple application. The tutorial is aimed at developers that will write applications using the API and there will be quite a few code examples. The finished application is also available for download, so please download it, read the code and test it. To get started you need access to the Apsis API. This is an add-on feature of APSIS Pro, contact your APSIS Account Manager or send an email to firstname.lastname@example.org to initiate activation.
Once you have REST API access you need to create an API key from within APSIS Pro. Please see the "Getting started" section for more details about API keys.
What we will buildWe will walk you through how to build a simple application that allows the user to list their mailing lists, create a new list and create subscribers on the list. The user will also be able to create newsletters and send a newsletter to a mailing list. This tutorial will show how to use the API from PHP, but you can use C#, Java, Python or whatever programming language you feel comfortable with. Also we will consistently request the API to return XML, even if we could just as well have used JSON.
Get a Mailing ListLet's get started by listing the existing mailing list in our account. This is done by calling the GetMailinglistsPaginated method. According to the method documentation we need to call the following URL to use the method:
PageNumber and PageSize allows us to divide all the mailing list into smaller subsets. For example we can return just 10 or 20 mailing list per request. To make our lives easy right now let's just get the first page and set the page size to 10, i.e. we will return just the first ten mailing lists. That makes the URL we need to call:
To make the request there are a couple of more things we need to specify; one is our API key and the other is in what format we want the response. Let's start with the API key. There are a couple of ways to set the API key, in this tutorial we will use the HTTP Basic auth method, i.e. to send the API key as a username in the URL. If our API Key is "abc123" that means that we would need to use this URL to call the GetMailinglistsPaginated method:
As a last configuration step of the API request we need to define in what format we want the response, our choices being XML or JSON. This is set in an HTTP Header when making the request, the header is "Accept" and it should be set to "text/xml" to get XML back or "application/json" to get JSON back. In this tutorial we will always request XML, but we could just as well have used JSON throughout.
Using PHP to implement this API call includes using cURL to make an HTTP request and then parse the response using http://php.net/manual/en/book.simplexml.php. If we instead used JSON the response could be parsed using json_decode(). This is the PHP code needed to call the GetMailinglistsPaginated method:
In the complete tutorial PHP application this call is done from the ApsisApiMethods class in the apsis_api_methods.php file. The function get_mailing_lists_paginated() in turn uses the get() function from the ApsisApi class in the apsis_api.php file, and it is this method that implements the actual cURL call. This is done to make the code as reusable as possible and to make it easy to just add new methods in the ApsisApiMethods class without having to touch the code that makes the actual API call. The data returned from this API call will be something like:
This response follows the same structure as all APSIS API responses. There is a Code that tells us the status of the request (1 = Successful), a Message that is a human readable status message and a Result that contains the actual data of the response. After parsing this XML with SimpleXML we have a PHP object that we can use in our code. This is how we can get an array of mailing lists:
Then it is easy to loop through all mailing lists and print out their name etc. This is all done in the mailing_lists.php file.
Note that GetMailinglistsPaginated only returns a subset of all existing mailing lists depending on the request parameters and the number of mailing lists. If you really want to get all of the mailing lists that belong to an account you should use the GetAllMailingLists method, which is a queued method rather than paginated (more about queued methods later).
Create a Mailing ListTo begin with we do not have any mailing lists, so let's add the functionality needed to add a new mailing list. This is done with the CreateMailinglist API method. This method is slightly different than the previously used GetMailinglistsPaginated method since CreateMailinglist is a POST method, i.e. it is called using HTTP POST since we are creating new data on the account. GetMailinglistsPaginated was called with a HTTP GET since the purpose was to retrieve data.
To call CreateMailinglist we need to use this URL:
We also need to specify some body parameters. These are parameters set in the body of the POST request in either a XML format or in JSON. This is an example of how an XML formatted body could look like:
Since we are sending either XML or JSON in the request body we need to set the Content-Type HTTP header to tell the API server which format we are using. Set it to either "text/xml" or "application/json" depending on what format you are sending. The PHP code to do this API call is quite similar to the code above, except that we need to specify that HTTP POST should be used, set the body and the Content-Type header. Assuming we already have a parameter called $body containing the XML we can make the request with this PHP code:
The data returned in the API response would be something like:
Once again with a Code, Message and Result. This time the Result contains the ID of the newly created Mailing List. This is implemented in the mailing_lists.php file using a simple HTML form to allow users to specify the parameters of the new mailing list.
Create SubscribersA mailing list needs to have subscribers. Listing subscribers for a mailing list is easily done with the GetMailinglistSubscribersPaginated method, similar to the GetMailinglistsPaginated method previously mentioned. Creating subscribers is a bit different however, since the CreateSubscribers method is a "queued" method. That means that the subscribers are added in batch on the server and the result might not be immediate. The purpose of using queued API methods is to reduce the load on APSIS Pro and to minimize the risk of a timeout, especially since an API call could potentially return hundreds of thousands of rows of data
To call CreateSubscribers a HTTP POST should be sent to:
The data of all the Subscribers to create are defined in the body of the POST request like this:
In this example only one user named John Andersson will be created, but it could just as well have been more subscribers being created. This POST request is made in the same way as the CreateMailinglist call above, the difference is in what the API call returns:
The response contains Code, Message and Result as usual. However the Result does not contain information about how the operation went, since this has not yet been executed by the server. Instead it contains a PollURL, which is a URL that we need to call until the server is done with creating the subscribers. Calling the PollURL is done with HTTP GET, i.e. in the same way as GetMailinglistPaginated above, and the response looks like this:
If there are a lot of subscribers added the State might be set to 1, which means that the operation is started but not completed yet. However, the state we are looking for is 2, which means the operation is completed. Keep calling the PollURL until you get either a completed operation or an error. Best practice is to call the PollURL with longer and longer pauses between each call and to set a limit to the number of calls made, otherwise your application might keep polling forever if something goes wrong.
This is an example of how the polling can be implemented in PHP:
The polling is done a maximum of 10 times with increasing pauses between each poll, from 0 to 9 seconds. If this code was to be used in production we should continue polling for up to an hour or two, since this is how long Queued methods might take.
Once the state is completed we need to make a GET request to the DataUrl returned from the polling. This is the URL containing the actual result and the return data from the API call. There we will find information if some subscribers failed to be created and if so, why it failed etc.
To sum it up, calling a queued method requires that we:
- Make a POST request to the API method's URL.
- Retrieve the PollURL from the response and keep polling that URL with a HTTP GET until you get a completed or an error.
- And, once the operation has completed you can get the data about the operation by making a GET request to the DataURL.
NewslettersWe can implement the listing and creating of Newsletters the same way that we did the listing and creating of Mailing Lists. Just use the CreateNewsletter and the GetNewslettersPaginated methods. Once we have a mailing list with at least one subscriber and we have created a newsletter we can send the newletter to the mailing list by using the SendNewsletter method.
Please see the complete PHP tutorial application and the API documentation for details about all these method calls.