Management API

In dit artikel vind je meer informatie over onze API voor Aangetekend Mailen. Heb je meer informatie nodig, neem dan contact op met onze support afdeling.

LET OP: Nieuwe API

Onze nieuwe API 2.0 is te vinden op: https://aangetekendmailen.stoplight.io/docs/aangetekend-mailen/
We hebben een nieuwe API 2.0 beschikbaar, onderstaande API beschrijving wordt niet verder doorontwikkeld.
Voor vragen hierover, neem contact op met support@aangetekendmailen.nl

Voorwaarden gebruik API

Om gebruik te kunnen maken van de API moet deze eerst door Aangetekend Mailen geactiveerd worden. Dit verzoek kan gemaild worden naar service@aangetekendmailen.nl.

Om gebruik te kunnen maken van de XML functionaliteit moet er een gebruikersnaam en wachtwoord aangemaakt worden. Dit is eenvoudig te realiseren door een “Webservicegebruiker” aan te maken in het dashboard.

Manier van aanroepen van de API

De API wordt aangeroepen door een HTTP-request te versturen naar een vaste URL. In een request moeten gebruikersnaam en wachtwoord meegegeven worden. Voor een aantal operaties is vereist dat een Json-bericht wordt meegestuurd.


In dit document wordt ervan uitgegaan dat als tool om requests te versturen gebruik gemaakt wordt van curl (zie https://curl.haxx.se/). Uiteraard kunnen hiervoor ook andere tools gebruikt worden.

Een voorbeeld van het aanroepen van de API is:

 

curl -u admin:admin -X DELETE https://<servernaam>.aangetekendmailen.nl/allowed_email_address/14

 

 

“servernaam.aangetekendmailen” is de servernaam zoals deze is ontvangen bij oplevering vanuit Aangetekend Mailen.
Dit kan, als daarvoor is gekozen, ook een ander taaldomein zijn (bv ‘digitaalaangetekend.be’).

Terugkoppelen van resultaten

De API koppelt resultaten van aangeroepen API request’s terug door middel van HTTP return codes. Sommige API request’s retourneren ook een Json-bericht met extra informatie.

Aangetekende mail versturen

Aangetekende mails kunnen op meerdere manieren verstuurd worden. Er is een Outlook plugin, hiervoor is een installatiehandleiding beschikbaar. De andere routes worden hier besproken.

Mail sturen via extensie

Een Aangetekende mail kan nu verstuurd worden naar de ontvangers op de volgende manier:

<e-mailadres>.<bedrijfsnaam>.aangetekendmailen.nl

Bijvoorbeeld: receiver@email.com.voorbeeld.aangetekendmailen.nl

Mail sturen via API

Wanneer je een aangetekende mail wilt versturen via de API dient de volgende code gebruikt te worden:

curl -H 'Content-Type: application/json;charset=UTF-8' --data-binary '{
    "message_body": "Dit is een test bericht.",
    "message_html": "<b>Dit is een test bericht.</b>",
    "sender_email": "afzender@email.com",
    "subject": "test bericht",
    "sender_real_name": "Voornaam Achternaam",
    "recipient_email": "receiver@email.com",
    "recipient_language": "nl",
    "attachments": [{
    "attachment": "VGVzdAo=",
    "attachment_name": "test.txt",
    "attachment_type": "application/txt"
    }, {
    "attachment": "RGl0IGlzIG5vZyBlZW4gdGVzdA==",
    "attachment_name": "test2.txt",
    "attachment_type": "application/txt"
    }]
}'
https://<servernaam>.aangetekendmailen.nl/webservice/mailsender/send/

 

De data in de attachment velden is de base64 gecodeerde inhoud van de attachments.

De volgende paramaters kunnen worden toegevoegd voor extra functionaliteit:

"enable_sign": "true"
"country_code": "31"
"phone_number": "0612345678"
"X-OWN-ID": "1234"
    "enable_mandate" : "true"
"enable_eidas": "true"
"custom_logo": "Base64 encoded logo"
    "cc_to_sender" :  "false"

 

Aangetekende mail succesvol aangenomen

Wanneer de aangetekende mail succesvol is aangenomen om verstuurd te worden wordt het volgende teruggegeven:

{
  "ticket_token": "tickettoken",
  "ticket_url": "https://<servernaam>.aangetekendmailen.nl/...",
  "message": "OK"
}

 

Aangetekende mail niet succesvol aangenomen

Wanneer de aangetekende mail niet succesvol is aangenomen om verstuurd te worden wordt het volgende teruggegeven:

{
  "message": "foutcode"
}

 

De volgende foutcodes zijn mogelijk:
• ERROR NO SENDER
• ERROR NO RECIPIENT
• ERROR NO SUBJECT
• ERROR NO MESSAGE BODY
• ERROR NO ATTACHMENT
• ERROR NO MIME TYPE
• ERROR NO FILENAME

Mail annuleren

Het Aangetekend Mailen proces kan afgesloten worden. Afsluiten hier betekent het beëindigen van de Aangetekend Mailen proces. Om een mail af te sluiten kan de volgende code gebruikt worden:

curl -u webservice:webservice -XPUT https://voorbeeld.aangetekendmailen.nl/webservice/endprocess?amail_token=abc&status_code=210

 

Er zijn drie status codes die hier gebruikt kunnen worden namelijk 210,220 en 230.
210: Afzender AM proces gestopt, reden A
220: Afzender AM proces gestopt, reden B
230: Afzender AM proces gestopt, reden C

Mail met succes afsluiten

Indien de mail met succes afgesloten is, wordt het volgende teruggegeven:

{
    "description": "E-Mail successfully closed with description: Afzender AM proces gestopt Reason A",
    "code": 200
}

 

De mail bestanden op de server worden eventueel verwijderd.

Mail ID of Customer ID bestaat niet

Indien de mail ID niet bestaat, wordt het volgende teruggegeven:

{
    "description": "E-Mail with id abc does not exist",
    "code":400
}

 

XML-koppeling

Via de XML-koppeling is het mogelijk om informatie behorende bij aangetekende mails op te vragen in XML-formaat via pull berichten. Om ervoor te zorgen dat dit alleen hoeft te gebeuren als er een wijziging heeft plaats gevonden is er een push mechanisme gebouwd waarmee het interne ID-nummer (ticket token) wordt verstuurd.

Push Update

Bij een ticketstatus-verandering wordt een GET-HTTP-request gedaan met één of meerdere 'token'-parameters. Deze token kan vervolgens gebruikt worden om de XML-webservice aan te roepen voor de details.
Er kunnen meerdere tokens tegelijk worden gestuurd, voor het geval er meerdere status-veranderingen tegelijk optreden.
Method:GET
URL Params: token=[alphanumeric] [*) kan meerdere keren voorkomen]
Aangetekend Mailen moet de URL waar deze berichten naar toe gestuurd moet worden invoeren op de AM-server, stuur een mail naar support@aangetekendmailen.nl als dit gewenst is.

Informatie ophalen

Als je via push op de hoogte bent gebracht kan je via XML de laatste gegevens ophalen. Deze laatste gegevens ophalen kan je op 2 manieren ophalen:

  1. Ticket token (heeft u via de push functionaliteit ontvangen)
  2. Uren (aangetekende mails die in de afgelopen hoeveelheid uren een update hebben gehad)

Ticket token

Om de informatie op te vragen aan de hand van een ticket token moet de volgende URL aangeroepen worden:

https://<servernaam>.aangetekendmailen.nl/webservice/xmlticket/?ticket-tokens=<ticket-token>

Bijvoorbeeld:

https://voorbeeld.aangetekendmailen.nl/webservice/xmlticket/?ticket-tokens=KnAzVtQv

 

Er kunnen ook meerdere ticket-tokens tegelijk worden opgegeven, bijvoorbeeld:

https://voorbeeld.aangetekendmailen.nl/webservice/xmlticket/?ticket-tokens=KnAzVtQv,MrW.W7Xv

 

Uren

Het is ook mogelijk om de informatie behorende bij Aangetekende Mails op te vragen die een statuswijziging gehad hebben in de bepaalde tijd. Hiervoor moet de volgende URL aangeroepen worden:

https://.aangetekendmailen.nl/webservice/xmlticket/hours/

 

Bijvoorbeeld:

https://voorbeeld.aangetekendmailen.nl/webservice/xmlticket/hours/5

 

Let erop dat dit altijd hele uren moeten zijn.

 

Koppelen aan eigen ID

In het vorige hoofdstuk behandelden we de situatie waarin er gebruik wordt gemaakt van het ID van Aangetekend Mailen. Het is ook mogelijk om een eigen ID aan een aangetekende mail te koppelen. Op die manier kan je de betreffende aangetekende mail koppelen aan jullie systeem.

ID koppelen

Een eigen ID kan aan de aangetekende mail gekoppeld worden door middel van het aanpassen van de mailheader. Dit ID kan toegevoegd worden door in de header het volgende toe te voegen:

X-OWN-ID: <eigen code>

 

Hierbij een voorbeeld van een header met de betreffende tekst:

Return-Path: sender@email.com
Received-SPF: None (no SPF record) identity=mailfrom; client-ip=12.123.123.123; helo=server.aangetekendmailen.nl; envelope-from=sender@email.com; receiver=
Received: from server.aangetekendmailen.nl (server.aangetekendmailen.nl [12.123.123.123])
by (Postfix) with ESMTP id BD1C3C179
for ;
Received: from mail pickup service by server.aangetekendmailen.nl with Microsoft SMTPSVC;

X-OWN-ID: 12345
MIME-Version: 1.0
From: sender@email.com
To:
Date:
Disposition-Notification-To: filter@receipts.voorbeeld.aangetekendmailen.nl
Subject:

 

Informatie ophalen aan de hand van eigen ID

Zoals de informatie opgehaald kan worden aan de hand van bijvoorbeeld een ticket token kan deze informatie ook opgehaald worden aan de hand van jullie eigen ID’s. Hiervoor moet de volgende URL aangeroepen worden:

https://<servernaam>.aangetekendmailen.nl/webservice/xmlticket/ customer/?custid=<ID>

 

Bijvoorbeeld:

https://voorbeeld.aangetekendmailen.nl/webservice/xmlticket/customer/?custid=5434
Er kunnen ook meerdere ID’s tegelijk worden opgegeven, bijvoorbeeld:
https://voorbeeld.aangetekendmailen.nl/webservice/xmlticket/customer/?custid=5434,5435

Telefoonnummer (2FA) meegeven via de header

Om een Aangetekende mail te versturen met 2FA kan een telefoonnummer meegestuurd worden via de header, gelijk aan de functionaliteit van de eigen ID. Een landnummer is bij aanlevering verplicht.
Dit doe je met:

Recipient-telephone: <telefoonnummer>

 

Voorbeeld: Recipient-telephone: +31612345678

Akkoord-knop instellen

Aangetekend Mailen bevat de optie om omgezet te worden naar een bevestigingsmail flow.
Hiermee kan een ontvanger direct vanuit de mail (zonder aankondiging) een akkoord geven op de verzonden informatie. Voor meer informatie hierover kan contact worden opgenomen met Aangetekend Mailen.

In dit hoofdstuk behandelen we hoe je zelf ontworpen en ontwikkelde bevestigingsmail aangepast moet worden. Deze aanpassingen bestaan uit de volgende onderdelen:

  1. Header aanpassen (door toevoegen van ID)
  2. De accepteren link (en indien gewenst afkeuren link)
  3. Toevoegen van de extensie aan het ontvangersadres (normale werking AM)

ID toevoegen aan mail header

Naast het toevoegen van de knoppen is het ook nodig jullie eigen ID toe te voegen aan de header van de mail. Het toevoegen van deze ID moet achter de tekst ‘X-OWN-ID’. Voor meer informatie zie hoofdstuk 4.1.

Accepteren en afkeuren

Om de bevestigingsmail te kunnen accepteren (of afkeuren) is het nodig om hier links voor aan te maken. Achter deze link moet het volgende komen te staan.

Acceptatie URL

De klant zal via uw mail de optie moeten hebben om de inhoud van de mail goed te keuren. Dit is mogelijk aan de hand van een link (bijvoorbeeld een button). De link zal moeten verwijzen naar het volgende adres:
//am_accept_placeholder//

In een voorbeeld ziet dat er zo uit:
<a ... href="//am_accept_placeholder//">Accepteren

Afkeuren URL

De klant zal (indien gewenst) via uw mail ook de optie moeten hebben om de inhoud van de mail te kunnen afkeuren. De link zal moeten verwijzen naar het volgende adres:
//am_reject_placeholder//

In een voorbeeld ziet dat er zo uit:
<a ... href="//am_reject_placeholder//">Weigeren

*In dit voorbeeld maken we gebruik van ‘//’ als actieteken, soms kan dit conflicteren, het is (op verzoek) ook mogelijk om met andere tekens te werken, bv ‘XX’ als in ="XXam_accept_placeholderXX">

Voorbeeld mail

KPN heeft de optie ‘bevestigingsmail instellen’ ingeschakeld. Dit is het eindresultaat:

API - voorbeeld mail

Op het moment dat de ontvanger op ‘Ja, akkoord’ klikt krijgt de verzender hier melding van en wordt het akkoord opgeslagen op het statusbiljet.

Beschikbare API requests

In dit hoofdstuk worden de verschillende API requests van de API beschreven en voorbeelden gegeven van gebruik van de API requests.
Dit kan met een snelle call waarin direct een gebruiker wordt aangemaakt, of losse calls voor als er meer keuzemogelijkheid gewenst is.

Snel een Gebruiker met dashboardrechten aanmaken

Hieronder de meest eenvoudige methode om een gebruiker aan te maken die ook direct toegang heeft tot het dashboard (alleen inzage in de Aangetekende mails verstuurd vanuit dit ene toegevoegde e-mailadres).

Snel aanmaken

Voor snel aanmaken van een gebruiker maak je gebruik van het volgende endpoint:

Body

{
  "email_address": "user@example.com"
}

 

Curl

curl -X POST "<servernaam>.aangetekendmailen.nl/api/user/ -H  "accept: application/json" -H  "Authorization: Basic" -H  "Content-Type: application/json" -d "{\"email_address\":\"user@example.com\"}"

 

Response:

{
 "id":123
}

 

Snel verwijderen

Curl

curl -X DELETE "<servernaam>.aangetekendmailen.nl/api/user/user@example.com" -H  "accept: */*" -H  "Authorization: Basic”

 

Alternatief gebruiker aanmaken

Een nieuwe gebruiker kan als volgt worden aangemaakt:

curl -u admin:admin -H 'Content-Type: application/json;charset=UTF-8' --data-binary '{"emailAddress":"user@example.com","allowed":true}' https://<servernaam>.aangetekendmailen.nl/allowed_email_address

 

Succesvol aanmaken van een gebruiker

Als de gebruiker succesvol aangemaakt wordt geeft de API een HTTP return statement, inclusief informatie van de aangemaakte gebruiker. Deze informatie bevat onder andere de identifier die gekoppeld is aan de aangemaakte gebruiker en tijdstip van creëren.
Voorbeeld:

{
  "emailAddress" : "user@example.com",
  "allowed" : true,
  "emailAddressStatusMail" : null,
  "entityId" : 123,
...
}

 

Fout tijdens aanmaken van een gebruiker

Indien de gebruiker al bestaat wordt een HTTP return code 500 teruggegeven. Een voorbeeld is:

{"error":"Error: 500"}

 

Gebruiker verwijderen

Bestaande gebruikers hebben een uniek ID, welke gebruikt kan worden om de gebruiker te verwijderen. Een gebruiker kan als het volgt worden verwijderd:

curl-u admin:admin -X DELETE https://<servernaam>.aangetekendmailen.nl/allowed_email_address/123

 
  • De 123 is de entityld uit de response van het aanmaken van een gebruiker.

Succesvol verwijderen van een gebruiker

Als de gebruiker met de opgegeven identifier bestaat, wordt deze verwijderd. In dat geval wordt er een status code 204: no content teruggegeven.

Gebruiker bestaat niet

Als er geen gebruiker met de opgegeven identifier bestaat wordt een HTTP return code 404 teruggeven, inclusief een omschrijving van de fout. Een voorbeeld is:

Status 404: not found.

 

Dashboardgebruiker aanmaken

Wanneer je een dasboardgebruiker wilt aanmaken dient de volgende code gebruikt te worden:

curl -u admin:admin -H 'Content-Type: application/json;charset=UTF-8' --data-binary '{"update":true,"name":"user@example.com","password":"A1!2@b3#4$C","role":"ROLE_USER","emailAddress":"user@example.com","userFilterList":"user@example.com"}' https://<servernaam>.aangetekendmailen.nl/dashboard_user

 

Dashboardgebruiker succesvol aangemaakt

Wanneer de dashboardgebruiker succesvol is aangemaakt wordt het volgende teruggegeven:

{
  "name" : "user@example.com",
  "role" : "ROLE_USER",
  "emailAddress" : "user@example.com",
  "userFilterList" : "user@example.com",
  "entityId" : 123,
...
}

 

Dashboardgebruiker aanmaken mislukt

Wanneer het mislukt is om de dashboardgebruiker aan te maken wordt het volgende teruggeven:

{"error":"Error: 500"}

 

7 XML schema

XML output die via de XML koppeling verkregen wordt, voldoet aan de onderstaande XSD.

API - XML schema
API - XML schema 2

 

XML Voorbeeld

API - XML voorbeeld