One of the projects I worked on was to create an API for our email platform that allowed the client to retrieve analytical data for their mailings.

The email platform already provided a way to get insights about sent mailings/email campaigns in the form of a web application with very detailed analytical data. It allows the client to see how many recipients really received the email, who actually opened it, which links were clicked on, on which devices this happened, and a lot more. But we did not have a way yet to exchange this information with other external systems. After receiving receiving questions about this from a number of clients, it was decided to build an API that the clients' systems could communicate with to retrieve the analytical data for their own means.

Development

While the features the API should get were not decided by me, I did get the responsibility to build the entire API. To me this was a very fun and educational assignment. The API was going to be developed for .NET Core 3.1 so that we could run the application on an Ubuntu server. At the time, I had limited experience with .NET Core and Ubuntu, asside from some tinkering I sometimes did at home. Now I had the chance to expand my knowledge on these subjects and use it for a real project. I was also given the time to do a lot of research first, which really helped.

During development of the API we also decided to no longer write the documentation ourselves. Instead we would automatically generate it using the Swagger OpenAPI standard. This meant I would have to take that into account when setting up the initial code so that the documentation would be correctly generated. By using an open standard it would also be relatively easy for a client to automatically generate code in their preferred programming language. For us it meant that we could easily make documentation available to the client and it would barely require any maintenance since everything is automatically generated.

To host the API, three new virtual servers were setup that run on Ubuntu: a development/test server and two production servers. These servers cannot be accessed by the internet, but are only accessible through the internal network. This is because in front of these servers we use an API manager called Kong that is responsible for the authentication. Kong API itself is placed behind a loadbalancer setup using haproxy.

Functionalities

The first version of the API would not contain all the functionalities of the full version yet. Only the methods that were at the time required for one of our clients were to be implemented. Afterwards the API would periodically be updated with new methods giving access to new analytical data.

The first version contained the following methods:

Mailing overview based on specified criteria

This method allows you to specify a set of criteria that the mailings you want to retrieve must match. You could for example retrieve mailings that use a specific message or subscription, or you could specify the time period in which the mailings should've been sent.

The result is a paginated list of mailings matching the specified criteria. Each mailing contains some basic information as well as a unique ID that can be used for retrieving in depth analytical data for the specific mailing.

Retrieving general details for a specific mailing

This methods retrieves detailed information about a specific mailing by it's unique ID. Among many other things, the information returned describes how many people the mailing was sent to, how many actually received it, or opened it or clicked on one of the mailing's links, etcetera.

Retrieving link and click details for a specific mailing

This method allows you to zoom in even further on a mailing, by retrieving information about the links present within the message that was sent. A paginated list with links is returned, where each link's details describe the URL it targets, what kind of link it is (for example: an external link or an unsubscription link), how many people clicked the link at least once, how many total clicks there are, and more.

Retrieving tag and score details for a specific mailing

This methods zooms in on the tags that were used in the mailing. Tags are keywords that can be attached to an email message, a specific action, or a link. When the recipient opens the email or clicks a link, the score for the associated tags is increased. Tags can be used for followup mailings. The API method returns a paginated list with the mailings tags and their scores.

Ping method

This method does not require a lot of explanation. It has the purpose of checking whether the API is available or not. If the API is running, the text "Pong" will be returned in the response.