REST API voor contacten

  1. Home
  2. Kennisbank
  3. API
  4. REST API voor contacten

De Inboxify REST API voor contacten (API) maakt het mogelijk om vanuit je eigen applicatie contacten op te zoeken, toe te voegen, te wijzigen of te verwijderen. De API is daarmee bijzonder geschikt voor het koppelen van je webshop, website of CRM-applicatie met Inboxify.

Tip! Om het werken met de API gemakkelijker te maken hebben we een PHP client ontwikkeld:https://gitlab.com/inboxify/inboxify-api-php

De API maakt gebruik van vier opdrachten:

Opdracht Actie Beschrijving
POST Toevoegen Een nieuw item toevoegen
GET Ophalen Een item of een lijst met items ophalen
PUT Wijzigen/Vervangen Een bestaand item wijzigen
DELETE Verwijderen Een bestaand item verwijderen

Locatie

De API kun je benaderen via https://api.inboxify.nl

Voor deze API proberen we het REST-principe zoveel mogelijk aan te houden. Dat wil onder meer zeggen dat de resources, in dit geval de contacten, een eigen URL hebben en deze via HTTP-methodes benaderd worden. Hieronder enkele voorbeelden:

POST https://api.inboxify.nl/contacts/webshopklanten voegt een nieuw contact toe aan de lijst webshopklanten
GET https://api.inboxify.nl/contacts/webshopklanten/1234567890 haalt het contact met id 1234567890 op uit de lijst webshopklanten
GET https://api.inboxify.nl/contacts/webshopklanten haalt de contacten uit de lijst webshopklanten op
PUT https://api.inboxify.nl/contacts/webshopklanten/1234567880 wijzigt het contact met id 1234567890 van de lijst webshopklanten
DELETE https://api.inboxify.nl/contacts/webshopklanten/1234567890 verwijdert het contact met id 1234567890 uit de lijst webshopklanten

Authenticatie

Om de API te benaderen kun je kiezen uit twee authenticatiemethoden:

  1. Basic authentication
  2. Signature based authentication

Voor beide authenticatiemethoden heb je een API- en een geheime sleutel nodig. Deze kun je vinden en in Inboxify aanmaken via “Mijn gegevens>Account>API-gegevens”.

Basic authentication

Dit is de makkelijkste methode. Bij elk verzoek stuur je een Authorization header mee. Deze header bevat het woord “Basic” en je API- en geheime sleutel gecodeerd in base64.

Stel je API-sleutel is “mijn sleutel” en je geheime sleutel is “geheime sleutel”. De ongecodeerde Authorization header komt er dan als volgt uit te zien:

Basic mijn sleutel:geheime sleutel

Nu is het zaak om “mijn sleutel:geheime sleutel” te coderen. De Authorization header wordt dan:

Basic bWlqbiBzbGV1dGVsOmdlaGVpbWUgc2xldXRlbA==

De volledig header ziet er dan als volgt uit:

Authorization: Basic bWlqbiBzbGV1dGVsOmdlaGVpbWUgc2xldXRlbA==

Signature based authentication

Deze authenticatiemethode maakt gebruik van vier componenten:

Component Te vinden Extra informatie
apikey Mijn gegevens>Account>API-gegevens>API-sleutel Stuur je mee als header
salt Willekeurig gegenereerd bij ieder verzoek die je maakt Stuur je mee als header
geheime sleutel Mijn gegevens>Account>API-gegevens>Geheime sleutel Stuur je NIET mee!
signature SHA256 hash van de salt met als hashing key de geheime sleutel Stuur je mee als header

Van deze vier componenten stuur je drie (apikey, salt en signature) mee als header.

Codevoorbeelden voor het generen van de signature vind je in bijlage 1.

Het JSON-object contact

De API maakt veelvuldig gebruik van het JSON-object contact. Zo wordt het object contact met de GET-methoden geretourneerd en stuur je het object contact mee met de POST- en PUT-methoden. Hieronder de velden van het object:
Naam Maximum lengte/opmerkingen
email 50, verplicht bij POST
list 25
companyName 100
firstName 50
insertion 20
lastName 50
sex 0, 1 of 2
address 70
postalCode 15
city 50
countryCode 3
telephone 20
mobile 20
remarks 500
free1 50
free2 50
free3 50
customDate Datum in format yyyy-mm-dd
tags Een array van strings, maximum lengte van 32 karakters per tag.
unsubscribed Met dit veld kun je een contact afmelden. Je kunt een eerder afgemeld contact met dit veld opnieuw aanmelden indien je in Inboxify via Mijn gegevens>Account>API-gegevens “Bevestigingsmail voor aanmeldingen” aan hebt staan.
bounced Alleen lezen. Indien true, dan is het adres door de (ontvangende) mailserver als onjuist aangemerkt.
registrationDate Alleen lezen. Datum van registratie.
De countryCode (landcode) is het drieletterige ISO-landcode waarbij NLD staat voor Nederland. Het veld sex (geslacht) is onder te verdelen in drie waarden:
Waarde Betekenis
0 Onbekend
1 Man
2 Vrouw
Het object contact kan er als volgt uitzien:

{
 "id": "49586A365865513156384E7A336542473842416532773D3D",
 "list": "Webshopklanten",
 "email": "janjansen@inboxify.nl",
 "companyName": "Inboxify",
 "firstName": "Jan",
 "insertion": "",
 "lastName": "Jansen",
 "sex": 1,
 "telephone": "0501234567",
 "mobile": "0612345678",
 "address": "Dorpsstraat 1",
 "postalCode": "0000 AA",
 "city": "Ons Dorp",
 "countryCode": "NLD",
 "unsubscribed": false,
 "bounced": false,
 "registrationDate": "2015-02-25T00:00:00",
 "free1": "",
 "free2": "",
 "free3": "",
 "customDate": null,
 "remarks": "",
 "tags": [
   "Merk A",
   "Merk B"
 ]
}

Methoden

GET https://api.inboxify.nl/contacts/{list}/{id}

Retourneert het object contact uit de lijst {list} met identifier {id}.
Parameters (roodgekleurd is verplicht)
{list} De lijstnaam van de lijst waarvan je het contact op wilt vragen. Indien je lijstnaam spaties bevat, raden we je aan om de lijstnaam te coderen.
{id} Unieke identifier. Wordt geretourneerd bij het opvragen van je contacten via één van de GET-methodes. Je mag hier ook het e-mailadres als identifier gebruiken.

GET https://api.inboxify.nl/contacts/{list}/?offset=$offset$&limit=$limit$&sort=$sort$

Retourneert een array van het object contact uit de lijst {list}. Retourneert tevens de header x-Total-Count met het totaal aantal items in de (gefilterde) lijst.
Parameters (roodgekleurd is verplicht)
{list} De lijstnaam van de lijst waarvan je het contact op wilt vragen. Indien je lijstnaam spaties bevat, raden we je aan om de lijstnaam te coderen.
$offset$ Startpositie, standaard 0.
$limit$ Aantal, standaard 20, maximum 1.000.
$sort$ ASC of DESC. Standaard ASC.
$unsubscribed$ Filter op afmeldingen, True of False. Standaard wordt er niet gefilterd.

POST https://api.inboxify.nl/contacts/{list}

Maakt een nieuw contact aan in de lijst {list}. Indien het contact correct aangemaakt is, dan wordt de status code 201 CREATED met het nieuw aangemaakte contact in de body geretourneerd. POST wordt niet gebruikt voor het wijzigen van contacten.
Parameters (roodgekleurd is verplicht)
{list} De lijstnaam van de lijst waaraan je het contact toe wilt voegen. Indien je lijstnaam spaties bevat, raden we je aan om de lijstnaam te coderen.
{contact} Het JSON-object contact dat je toe wilt voegen stuur je in de body mee.
Voorbeeld POST https://api.inboxify.nl/contacts/webshopklanten met als body {"email":"janjansen@inboxify.nl", "tags":["Merk A", "Merk B"]} Retourneert status code 201 CREATED met JSON-object contact in de body:

{
 "id": "49586A365865513156384E7A336542473842416532773D3D",
 "list": "Webshopklanten",
 "email": "janjansen@inboxify.nl",
 "companyName": "",
 "firstName": "",
 "insertion": "",
 "lastName": "",
 "sex": 0,
 "telephone": "",
 "mobile": "",
 "address": "",
 "postalCode": "",
 "city": "",
 "countryCode": "",
 "unsubscribed": false,
 "bounced": false,
 "registrationDate": "2015-02-25T00:00:00",
 "free1": "",
 "free2": "",
 "free3": "",
 "customDate": null,
 "remarks": "",
 "tags": [
   "Merk A",
   "Merk B"
 ]
}

POST https://api.inboxify.nl/contacts/{list}/bulk-insert?overwrite=$overwrite$

Voegt meerdere contacten toe aan de lijst {list}. Retourneert status code 200 OK bij het succesvol uitvoeren van de methode. Adressen die niet toegevoegd konden worden, worden in een lijst met foutmeldingen geretourneerd.
Parameters (roodgekleurd is verplicht)
{list} De lijstnaam van de lijst waaraan je het contact toe wilt voegen. Indien je lijstnaam spaties bevat, raden we je aan om de lijstnaam te coderen.
Array van {contact} Het JSON-object contact dat je toe wilt voegen stuur je in de body mee.
$overwrite$ True of False. Standaard False. Bij True worden bestaande contacten met de nieuwe data overschreven.

POST https://api.inboxify.nl/contacts/{list}/bulk-delete?unsubscribe={unsubscribe}

Verwijdert meerdere contacten ineens uit de lijst {list}. Retourneert status code 200 OK bij het succesvol uitvoeren van de methode. Adressen die niet verwijderd konden worden, worden in een lijst met foutmeldingen geretourneerd.
Parameters (roodgekleurd is verplicht)
{list} De lijstnaam van de lijst waaruit je de contacten wilt verwijderen. Indien je lijstnaam spaties bevat, raden we je aan om de lijstnaam te coderen.
Array van {contact} Het JSON-object contact dat je toe wilt voegen stuur je in de body mee.
$unsubscribe$ True of False. Standaard False. Bij True worden contacten niet alleen verwijderd, maar ook afgemeld.

POST https://api.inboxify.nl/contacts/{list}/bulk-unsubscribe

Meldt meerdere contacten af uit de lijst {list}. Retourneert status code 200 OK bij het succesvol uitvoeren van de methode. Adressen die niet afgemeld konden worden, worden in een lijst met foutmeldingen geretourneerd.
Parameters (roodgekleurd is verplicht)
{list} De lijstnaam van de lijst waarvan je de contacten af wilt melden. Indien je lijstnaam spaties bevat, raden we je aan om de lijstnaam te coderen.
Array van {contact} Het JSON-object contact dat je toe wilt voegen stuur je in de body mee.

PUT https://api.inboxify.nl/contacts/{list}/{id}

Wijzigt een bestaand contact. Retourneert status code 200 OK bij een succesvolle wijziging. Gegevens die je niet meestuurt, worden niet gewijzigd.
Parameters (roodgekleurd is verplicht)
{list} De lijstnaam van de lijst waarvan je het contact wilt wijzigen. Indien je lijstnaam spaties bevat, raden we je aan om de lijstnaam te coderen.
{id} Unieke identifier. Wordt geretourneerd bij het opvragen van je contacten via één van de GET-methodes. Je mag hier ook het e-mailadres als identifier gebruiken.
{contact} Het JSON-object contact dat je wilt wijzigen stuur je in de body mee.

DELETE https//api.inboxify.nl/api/contacts/{list}/{id}

Verwijdert het contact uit de lijst {list} met identifier {id}. Retourneert 204 NO CONTENT bij succesvolle verwijdering.
Parameters (roodgekleurd is verplicht)
{list} De lijstnaam van de lijst waarvan je het contact wilt verwijderen. Indien je lijstnaam spaties bevat, raden we je aan om de lijstnaam te coderen.
{id} Unieke identifier. Wordt geretourneerd bij het opvragen van je contacten via één van de GET-methodes. Je mag hier ook het e-mailadres als identifier gebruiken.

GET https://api.inboxify.nl/api/contacts/{list}/{id}/tags

Retourneert een array met de tags van het contact met identifier {id} uit de lijst {list}.
Parameters (roodgekleurd is verplicht)
{list} De lijstnaam van het contact waarvan je de tags op wilt vragen. Indien je lijstnaam spaties bevat, raden we je aan om de lijstnaam te coderen.
{id} Unieke identifier. Wordt geretourneerd bij het opvragen van je contacten via één van de GET-methodes. Je mag hier ook het e-mailadres als identifier gebruiken.

POST https://api.inboxify.nl/api/contacts/{list}/{id}/tags

Voegt een tag toe aan het contact met identifier {id} uit de lijst {list}
Parameters (roodgekleurd is verplicht)
{list} De lijstnaam van het contact waaraan je de tags toe wilt voegen. Indien je lijstnaam spaties bevat, raden we je aan om de lijstnaam te coderen.
{id} Unieke identifier. Wordt geretourneerd bij het opvragen van je contacten via één van de GET-methodes. Je mag hier ook het e-mailadres als identifier gebruiken.
{tag} De tag die je toe wilt voegen stuur je in de body mee.

DELETE https://api.inboxify.nl/api/contacts/{list}/{id}/tags/{tag}

Verwijdert de opgegeven tag {tag} van contact met identifier {id} uit de lijst {list}. Retourneert 204 NO CONTENT bij succesvolle verwijdering.
Parameters (roodgekleurd is verplicht)
{list} De lijstnaam van het contact waarvan je de tag wilt verwijderen. Indien je lijstnaam spaties bevat, raden we je aan om de lijstnaam te coderen.
{id} Unieke identifier. Wordt geretourneerd bij het opvragen van je contacten via één van de GET-methodes. Je mag hier ook het e-mailadres als identifier gebruiken.
{tag} De tag die je wilt verwijderen.

Bijlage 1 – Genereren signature

In deze bijlage vind je enkele voorbeelden voor het genereren van de signature (bron: Kayako)

PHP voorbeeld


<?php
  $apiKey = "apikey";
  $secretKey = "secretkey";
  // Generates a random string, using microtime to make sure salt is not used before
  $salt = sha1(microtime(true));
  // Computes the signature by hashing the salt with the secret key as the key
  $signature = hash_hmac('sha256', $salt, $secretKey, true);
  // base64 encode...
  $encodedSignature = base64_encode($signature);
  // urlencode...
  $encodedSignature = urlencode($encodedSignature);
  echo "Voila! A signature: " . $encodedSignature;
?>

C# voorbeeld


using System.Security.Cryptography;
using System.Text;

namespace InboxifyContactsAPI
{    
  class Program
    {
      static void Main()
        {
          var apiKey = "apikey";
          var secretKey = "secretkey";

          // Generate a new globally unique identifier for the salt
          var salt = System.Guid.NewGuid().ToString();
 
          // Initialize the keyed hash object using the secret key as the key
          HMACSHA256 hashObject = new HMACSHA256(Encoding.UTF8.GetBytes(secretKey));
 
          // Computes the signature by hashing the salt with the secret key as the key
          var signature = hashObject.ComputeHash(Encoding.UTF8.GetBytes(salt));
 
          // Base 64 Encode
          var encodedSignature = Convert.ToBase64String(signature);
 
          // URLEncode
          encodedSignature = System.Web.HttpUtility.UrlEncode(encodedSignature);
 
          Console.WriteLine("Voila! A signature: " + encodedSignature);
 
          Console.ReadKey();
         }
    }
}

In dit artikel