Een klant die van onze producten gebruik maakte om nieuwsbrieven per e-mail te sturen kwam met de wens om dezelfde nieuwsbrieven in een eigen archief beschikbaar te kunnen stellen. Om maatwerk oplossing te voorkomen en de functionaliteit voor meer klanten in te kunnen zetten, is er gekozen voor een generieke oplossing waarbij verzonden mailings via een API worden ontsloten.

Opslag

Wanneer een mailing wordt verzonden wordt deze opgeslagen in een MongoDB database. Hierbij wordt de mailing in twee delen opgesplitst: de mailing data en het bijbehorende HTML document.

De data bevat alle informatie van de mailing waaronder het tijdstip van verzenden, de afzendernaam, welk bericht er is gebruikt en naar welk nieuwsbrief abonnement er is verzonden. Naast deze gegevens wordt er ook extra informatie opgeslagen in de vorm van metadata, wat is uitgelezen uit de HTML van het verzonden e-mailbericht. De API is zo opgezet dat er zeer efficiënt naar mailings gezocht kan worden op basis van deze metadata.

De ongepersonaliseerde HTML van de mailing zelf wordt los opgeslagen en kan worden opgehaald met het unieke ID die iedere gearchiveerde mailing heeft gekregen.

Metadata

Zoals eerder omschreven wordt er bij een mailing ook metadata opgeslagen. Dit zijn sleutelwaardes die vrij simpel aan een mailing kunnen worden toegevoegd, namelijk door deze direct in de HTML te plaatsen. Dit wordt gedaan volgens de HTML Microdata specificatie. Dit is een extensie op HTML waarmee het mogelijk is om gestructureerde data binnen een HTML document toe te voegen, zonder dat dit de opmaak van de HTML beïnvloedt.

Om HTML Microdata uit te kunnen lezen en om te zetten naar metadata voor de mailing, is er een parser geschreven die volledig voldoet aan de specificatie.

Door de metadata op deze manier direct in de HTML te plaatsen ben je niet afhankelijk van software die dit voor je doet, maar kun je tegelijkertijd ook heel gemakkelijk functionaliteit aan bestaande software toevoegen om dynamisch deze gegevens in de HTML te plaatsen. Dat laatste hebben we dan ook gedaan om onze editors uit te breiden, zodat gebruikers gemakkelijk via de user interface deze metadata toe kunnen voegen zonder de HTML aan te moeten passen.

In de praktijk wordt deze metadata gebruikt om bijvoorbeeld een nieuwsbrief naam en taal mee te geven. De klant kan dan vervolgens via de API gericht zoeken op mailings die in hun metadata een specifieke nieuwsbrief naam met een specifieke taal hebben staan.

API

Om de mailings op te kunnen halen is er een RESTful ASP.NET Web API ontwikkeld. Om hier gebruik van te kunnen maken dient de archief functionaliteit wel expliciet ingeschakeld te zijn voor de klant. De klant kan dan vervolgens de API aanroepen om naar mailings te zoeken en op die manier zelf een archief op hun website op te bouwen.

Authenticatie

De API is achter een API gateway geplaatst genaamd Kong. Hiermee wordt onder andere de authenticatie geregeld. Deze authenticatie gebeurt door middel van OAuth 2.

Functionaliteiten

De API bevat de volgende functionaliteiten.

Mailings zoeken op basis van criteria

De klant kan gepagineerd de data van mailings ophalen die voldoen aan bepaalde criteria. Deze criteria kan bijvoorbeeld bevatten in welke periode de mailing is verstuurd, naar welk abonnement en welke metadata de mailing heeft. Het resultaat is een pagina met gedetailleerde informatie over de mailings, met uitzondering van de HTML zelf. Deze kan apart worden opgehaald.

Een specifieke mailing ophalen op basis van de ID

Bij het gepagineerd ophalen van mailings krijg je ook de ID's van mailings terug. Met deze ID kun je ook voor een individuele mailing de details ophalen, exclusief de HTML.

De HTML van een mailing ophalen

Met de ID die je terug krijgt in de details van een opgehaalde mailing kun je ook de bijbehorende HTML ophalen. Dit is de ongepersonaliseerde HTML. Dat wil zeggen: hier staan geen persoonlijke gegevens in van een ontvanger, zoals een voor- of achternaam.

Metadata sleutels zoeken op basis van criteria

Metadata wordt opgeslagen als sleutelwaarden. Je kunt dezelfde criteria gebruiken als wanneer je mailings op wilt zoeken, om een overzicht op te halen van alle beschikbare metadata sleutels.

Metadata sleutels zoeken op basis van een sleutel en criteria

Wanneer je een metadata sleutel weet kun je deze, samen met dezelfde criteria als voor mailings, gebruiken om alle bestaande metadata waarden op te halen. Wanneer je bijvoorbeeld een metadata sleutel hebt genaamd "nieuwsbrief-naam" kun je alle waarden hiervoor opzoeken om een overzicht te maken van alle beschikbare nieuwsbrieven in het archief.

Voorbeeld van gebruik

De API zou als volgt gebruikt kunnen worden:

1. De klant plaatst de nieuwsbrief naam als Microdata in de HTML;
2. De klant gebruikt de API om alle nieuwsbrief namen op te halen door naar de waarden van deze sleutel te zoeken;
3. De klant bouwt hiermee een overzicht van alle beschikbare nieuwsbrieven;
4. Een bezoeker klikt op een van deze nieuwsbrieven;
5. Een pagina met mailings voor deze nieuwsbrief wordt via de API opgehaald;
6. De bezoeker kiest voor één van deze mailings;
7. De HTML van deze mailing wordt via de API opgehaald en aan de bezoeker getoond.