Handleiding: Koppelen met Marcom via de REST API

Transcriptie

1 Handleiding: Koppelen met Marcom via de REST API

2 Inleiding MailPlus Marcom is een marketing oplossing, waarmee een marketeer eenvoudig professionele nieuwsbrieven kan opstellen en versturen. Het is ook mogelijk om automatische geavanceerde event driven marketingcampagnes te aan te sturen. Bijvoorbeeld naar aanleiding van een gebeurtenis in een extern systeem. In de rapportage van elke verstuurde nieuwsbrief is terug te zien wat de effectiviteit is geweest. Het is mogelijk om MailPlus Marcom te koppelen met een extern systeem. Contacten kunnen realtime vanuit het externe systeem worden gesynchroniseerd naar MailPlus Marcom. Omdat de contacten door de synchonisatie al in MailPlus staan, kan de nieuwsbrief op elk gewenst moment verstuurd worden zonder extra handelingen van de marketeer. Voor een goede koppeling tussen het externe systeem en MailPlus Marcom is een REST API beschikbaar. Er dient hiervoor wel een koppeling ontwikkeld te worden die met deze REST API communiceert. Dit document beschrijft wat een ontwikkelaar moet weten om zo n koppeling te maken. Handleiding: Koppelen met Marcom via de REST API 1

3 Inhoudsopgave 1 INTRODUCTIE GLOBALE WERKING Schema van een koppeling OPZET KOPPELING OP BASIS VAN REST API Authenticatie OAuth (Open Authorization) API Key en Secret API URL API methodes XML en JSON Standaard methode formaat Foutafhandeling Statuscodes Maak gebruik van een wachtrij Hoe werkt het wachtrijprincipe? CONTACTEN SYNCHRONISEREN Welke contacteigenschappen worden gesynchroniseerd? Contact toevoegen aan MailPlus Marcom Contact wijzigen in MailPlus Marcom Contact verwijderen uit MailPlus Marcom Contact opzoeken in MailPlus Marcom Ontdubbeling vindt plaats in MailPlus WIJZIGINGEN, AFMELDINGEN EN BOUNCES Wijzigingen ophalen uit MailPlus Marcom Handleiding: Koppelen met Marcom via de REST API 2

4 5.2 Afmeldingen ophalen uit MailPlus Marcom Bounces ophalen uit MailPlus Marcom TRIGGEREN VAN AUTOMATISCHE CAMPAGNES REFERRENTIE REST API METHODES Methode: Contact toevoegen Methode: Contact wijzigen Methode: Contact ophalen Methode: Gewijzigde contacten ophalen Methode: Gebouncede contacten ophalen Methode: Contacteigenschappen ophalen Methode: Contacten opzoeken op basis van eigenschap Methode: Alle campagnes ophalen Methode: Campagne triggeren Methode: Campagne stoppen AANVULLENDE INFORMATIE Handleiding: Koppelen met Marcom via de REST API 3

5 1 Introductie MailPlus Marcom kent 2 productversies: 1) MailPlus Marcom Mailer MailPlus Marcom Mailer is bedoeld voor de praktische marketing professional. Naast het opstellen en versturen van s kunt u ook conversiegerichte landingspagina s maken voor ontvangers die doorklikken. Daarnaast zijn webformulieren om mensen te registreren voor bijvoorbeeld een evenement ook mogelijk. Maar ook follow-up s, documentenlinks en communiceren via SMS zijn allemaal aanwezig. Uitgebreide rapportages van de response van ontvangers op uw verzonden mailings maken het product compleet. 2) MailPlus Marcom Campaigns MailPlus Marcom Campaigns is een uitgebreide, schaalbare marketing oplossing die ondermeer marketing automation mogelijk maakt. Hiermee kunt u event-driven marketing toepassen. In dit document beschrijft hoe een ontwikkelaar een koppeling kan ontwikkelen tussen een extern systeem en MailPlus. In hoofdstuk 2 wordt eerst ingegaan op de globale werking van de koppeling. Hoofdstuk 3 beschrijft de algemene opzet van de koppeling op basis van REST API. In de hoofdstukken die daarop volgen worden de hoofdonderdelen behandelt van de koppeling, te weten: Contacten synchroniseren, Bounces en Afmeldingen ophalen en Campagnes triggeren. Hoofdstuk 7 is een referrentie van alle REST API methodes. Het document wordt beëindigd met een hoofdstuk Aanvullende informatie. Handleiding: Koppelen met Marcom via de REST API 4

6 2 Globale werking Een koppeling tussen een extern systeem en MailPlus Marcom kan grofweg uit vijf onderdelen bestaan: 1. Realtime synchronisatie van contactgegevens naar MailPlus. 2. Periodiek ophalen van contacten die hun profielgegevens hebben gewijzigd in MailPlus. 3. Periodiek ophalen van afmeldingen. 4. Periodiek ophalen van hard bounces. 5. Het triggeren van automatische event-driven marketingcampagnes. 2.1 Schema van een koppeling In bovenstaand schema is te zien dat MailPlus Marcom beschikt over een REST API. Hiermee wordt de koppeling gelegd. Daarvoor is aan de kant van het externe systeem een stukje software nodig. We noemen dit een connector of een plugin. De contactpersonen in de database van het externe systeem worden door de connector realtime met MailPlus Marcom synchroon gehouden. Dit wordt gesymboliseerd door de pijl naar rechts. Wanneer ontvangers van een nieuwsbrief hun profielgegevens wijzigen op een landingspagina in MailPlus Marcom, is het mogelijk om deze wijzigingen periodiek op te halen. Dat is de pijl naar links in het schema. Ditzelfde geldt voor afmeldingen en bounces. Ten slotte, kan het externe systeem eventdriven marketingcampagnes aansturen op het moment dat er een gebeurtenis plaatsvindt in het externe systeem. Zo kan het externe systeem ervoor zorgen dat er een wordt verstuurd vanuit MailPlus Marcom naar een contactpersoon die van prospect naar klant is omgezet. Ook dit wordt gesymboliseerd door de pijl naar rechts. Handleiding: Koppelen met Marcom via de REST API 5

7 3 Opzet koppeling op basis van REST API 3.1 Authenticatie Het is van belang dat de service kan verifiëren of de API aanroepen wel van de juiste bron (uw externe systeem) komen. Daarom vindt er bij bij het gebruik van de REST API service bij iedere aanroep authenticatie plaats OAuth (Open Authorization) De authenticatie is op basis van 2-leg Open Authorization (OAuth). Bij iedere API-aanroep dient er een zogenaamde Key en Secret meegegeven te worden, waarmee de API-service kan bepalen of de aanroep in orde is. De tokens kunnen nul blijven API Key en Secret Keys en Secrets zijn altijd gekoppeld aan één MailPlus-account. Er dient eerst in het MailPlus-account een Key en Secret aangemaakt te worden voor het externe systeem waarmee MailPlus gekoppeld wordt. Ga hiervoor naar het vierde tabblad MailPlus Instellingen op de startpagina. Hier kunt een nieuwe authorisatie aanmaken. U dient een authorisatie een naam te geven. Het is daarbij handig om een logische naam te geven. Bijvoorbeeld de naam van het externe systeem. Als u de authorisatie heeft aangemaakt, toont MailPlus de Key en Secret die u nodig heeft in het externe systeem. De API Key is in feite uw API wachtwoord en moet meegegeven worden aan elke API-aanroep. Net als bij elk wachtwoord, is het van belang dat u de Key en Secret veilig bewaart en alleen deelt met anderen die u vertrouwt met uw gegevens API URL Alle REST API aanroepen hebben de volgende URL als basis: N.B.: Deze URL werkt alleen als er een methode op de juiste manier wordt aangesproken. Handleiding: Koppelen met Marcom via de REST API 6

8 3.2 API methodes XML en JSON De API kan met zowel XML als JSON overweg. Bij het opsturen van gegevens, zal de header Content-Type gezet moeten worden met als waarde application/xml of application/json om respectievelijk XML of JSON op te sturen. Om te bepalen of de API XML of JSON teruggeeft, kan de header Accept worden gezet met als waarde respectievelijk application/xml of application/json Standaard methode formaat Het standaard methode formaat van alle REST API verzoeken is: METHOD /transaction?parameters METHOD GET, POST, PUT, of DELETE Transaction De API service die u wilt aanspreken, bijvoorbeeld contact. Parameters (indien GET) De aanvullende parameters die mogelijk meegegeven kunnen worden aan een API-verzoek. Alle parameter waardes dienen URL encoded te zijn. Ter illustratie: spaties dienen te worden omgezet naar "%20". Veel gangbare programmeertalen, zoals Java, Javascript, en PHP hebben built-in functions die hiervoor kunnen zorgen. Response De response van alle REST API aanroepen is JSON of XML. U kunt zelf bepalen wat u het prettigst vindt werken. Handleiding: Koppelen met Marcom via de REST API 7

9 3.3 Foutafhandeling Indien er iets niet goed gaat, geeft de API-service een foutmelding terug in XML of JSON. U krijgt dan altijd een errortype en een message terug Statuscodes MailPlus geeft één van de volgende drie statuscodes terug bij een fout: 400: Bad request A given value was invalid (e.g. wrong adres for a contact) 401: Unauthorized Wrong credentials (key and secret) given 404: Not found The given resource does not exists (e.g. when doing an update on a contact which does not exists in MailPlus) 3.4 Maak gebruik van een wachtrij Er kan altijd iets mis zijn met de verbinding tussen het externe systeem en MailPlus Marcom. Dit kan verschillende oorzaken hebben. Bijvoorbeeld omdat de server waar het externe systeem op draait tijdelijk geen internetverbinding heeft. Het is verstandig om hier rekening mee te houden bij het ontwikkelen van een connector Hoe werkt het wachtrijprincipe? De connector moet altijd eerst gewoon een REST API methode aanroepen op het moment dat het er toe doet. Pas als dat niet gelukt is, omdat er iets mis is met de verbinding tussen het externe systeem en MailPlus Marcom, dan moet de aanroep automatisch worden opgeslagen in een wachtrij. Op deze manier is de connector in staat om nieuwe pogingen te doen om de aanroep alsnog te laten lukken. Het heeft geen zin om dit in de eeuwigheid te blijven proberen als er iets structureel mis is met verbinding. Het advies is om het een beperkt aantal keer opnieuw te proberen met een oplopende interval. Dus bijvoorbeeld de eerste keer na 1 minuut, dan na 5 minuten, dan na 10 minuten, dan na een uur, et cetera. De wachtrij wordt op chronologische volgorde afgewerkt. Het is raadzaam om de wachtrij van mislukte aanroepen in een overzicht te tonen in het backend van het externe systeem. Dan is achteraf zichtbaar of er mislukte aanroepen zijn geweest en welke dat waren. Als een aanroep bij een herhaalpoging alsnog gelukt is, mag deze uit het overzicht verdwijnen. Handleiding: Koppelen met Marcom via de REST API 8

10 4 Contacten synchroniseren Voor een marketeer die MailPlus inzet om nieuwsbrieven mee te versturen, is het prettig dat het contactenbestand altijd up-to-date is. Zo kan de nieuwsbrief er op elk gewenst moment uit. Het is daarom wenselijk om contacten (near-) realtime te synchroniseren naar MailPlus. 4.1 Welke contacteigenschappen worden gesynchroniseerd? Er zijn een aantal contactvelden standaard beschikbaar in MailPlus Marcom, zoals Voor- en Achternaam, adres, et cetera. Om precies te weten welke velden dit zijn kunt u het beste gebruikmaken van een REST API methode die deze velden ophaalt. Als resultaat krijgt u niet alleen de veldnamen te zien, maar ook de formaten waarin deze dienen te worden opgeslagen. In MailPlus Marcom kan gebruik worden gemaakt van permissies. Dat wil zeggen dat een contact zich kan inschrijven of juist afmelden voor een specifieke ing. 4.2 Contact toevoegen aan MailPlus Marcom Als er een nieuw contact ontstaat in het externe systeem, dan kan deze direct worden ingeschoten in MailPlus Marcom via de REST API. 4.3 Contact wijzigen in MailPlus Marcom In het externe systeem kunnen er diverse plekken zijn waar contactgegevens wijzigen. Zodra er een contactwijziging plaatsvindt, dient de wijziging direct doorgegeven te worden aan MailPlus Marcom. Er zijn twee methodes om contacten in MailPlus Marcom te wijzigen. Door middel van de methode om contacten toe te voegen waarbij update op true wordt gezet. Deze methode wordt aanbevolen, want dan hoeft het externe systeem niet te onthouden of een contact mogelijk al eens eerder is ingeschoten. De andere methode is specifiek voor het wijzigen van een contact. Handleiding: Koppelen met Marcom via de REST API 9

11 4.4 Contact verwijderen uit MailPlus Marcom Het is niet mogelijk om contacten te verwijderen uit MailPlus Marcom. Zo blijft de historie van ings uit het verleden in tact. Bovendien is het van belang dat hard bounces en afmeldingen blijven bestaan in MailPlus Marcom om te voorkomen dat iemand ten onrechte alsnog nieuwe e- mailings ontvangt. Als een contact wordt verwijderd in het externe systeem, dan dienen alle permissies van dat contact uitgezet te worden in MailPlus Marcom door het contact te wijzigen. 4.5 Contact opzoeken in MailPlus Marcom Het is mogelijk om een contact in MailPlus Marcom op te zoeken op basis van een bepaalde eigenschap of op basis van een combinatie van verschillende eigenschappen. 4.6 Ontdubbeling vindt plaats in MailPlus Wanneer u de REST API gebruikt om contacten in te schieten, dan gelden de ontdubbelregels die in het MailPlus-account staan ingesteld. Standaard betekent dit dat er wordt ontdubbeld op het externe contactid en het e- mailadres. Als er een contact wordt ingeschoten dat al bestaat in MailPlus, dan worden de ingeschoten gegevens samengevoegd met het bestaande contact. Zo ontstaan er dus geen dubbele contacten in MailPlus, wat ervoor zorgt dat ontvangers geen mailing dubbel in hun inbox krijgen. Wilt u meer weten over hoe de ontdubbeling precies werkt in MailPlus, neem dan contact op met MailPlus Support. Handleiding: Koppelen met Marcom via de REST API 10

12 5 Wijzigingen, Afmeldingen en Bounces Het externe systeem hoeft niet altijd leidend te zijn voor alle contactgegevens. Er zijn een paar situaties die plaatsvinden in MailPlus Marcom. Het gaat om de volgende zaken: Ontvangers van een ing die hun gegevens wijzigen op een landingspagina in MailPlus Marcom. Ontvangers van een ing die zichzelf afmelden. Ontvangers van een ing waarvan het adres is gebounced. Deze zaken dienen periodiek te worden opgehaald door het externe systeem om de gegevens in het externe systeem up-to-date te houden. 5.1 Wijzigingen ophalen uit MailPlus Marcom Elke ing die wordt verstuurd vanuit MailPlus Marcom heeft een link in het bericht opgenomen waarmee de ontvanger zijn of haar contactgegevens kan wijzigen op een landingspagina in MailPlus Marcom. In principe kunnen dat alle gegevens zijn die bekend zijn van dat contact in MailPlus Marcom. Als het adres tevens wordt gebruikt in het externe systeem als gebruikersnaam om in te loggen als klant, dan is het raadzaam om dit veld niet op te nemen in het formulier op de profielwijzigpagina in MailPlus Marcom. Als ontvangers hun adres willen wijzigen, dan dienen ze dat te doen in het externe systeem. Contactwijzigingen uit MailPlus Marcom dienen periodiek te worden opgehaald door het externe systeem. Bijvoorbeeld één keer per uur of één keer per dag. Bij de methode om contactgegevens op te halen dient het externe systeem een start- en eindtijd van de afgelopen periode mee te sturen sinds de vorige ophaalactie. Het is daarbij raadzaam om een marge van minstens 10 minuten aan te houden tussen het moment van ophalen en de eindtijd van de periode. Als die tijden precies gelijk gehouden zouden worden, dan bestaat er de mogelijkheid dat er wijzigingen gemist worden. Handleiding: Koppelen met Marcom via de REST API 11

13 5.2 Afmeldingen ophalen uit MailPlus Marcom Elke ing die wordt verstuurd vanuit MailPlus Marcom heeft een link in het bericht opgenomen waarmee de ontvanger zichzelf kan afmelden voor toekomstige ings van gelijke soort. In feite is een afmelding hetzelfde als een contactwijziging, omdat een afmelding een verandering betekent van één of meerdere permissies van het contact. Het permissie-veld van een contact is niet anders dan andere contactvelden. Daarom kunnen afmeldingen met dezelfde methode als het ophalen van wijzigingen periodiek worden opgehaald door het externe systeem. 5.3 Bounces ophalen uit MailPlus Marcom Bij iedere ing die wordt gedaan in MailPlus Marcom kunnen er bounces ontstaan. De is dan niet bij de desbetreffende ontvanger aangekomen. Bij een soft bounce is er sprake van een tijdelijke situatie. Hier hoeft het externe systeem niets mee te doen. Als er sprake is van een hard bounce, dan is het adres van het desbetreffende ontvanger niet in orde. Het kan gaan om een typefout of het adres bestaat gewoonweg niet meer. Hard bounces dienen periodiek door het externe systeem opgehaald te worden uit MailPlus Marcom. In de eerste plaats om het bestand in het externe systeem schoon te houden en in de tweede plaats om er eventueel een vervolgactie aan te koppelen. Bijvoorbeeld het nabellen van de desbetreffende klant. Eventueel kunt u een melding tonen aan de consument bij de eerstvolgende keer dat hij of zij is ingelogd in het externe systeem. Ook bij de methode om bounces op te halen dient het externe systeem een start- en eindtijd van de afgelopen periode mee te sturen sinds de vorige ophaalactie. En ook daarbij is het raadzaam om een marge van minstens 10 minuten aan te houden tussen het moment van ophalen en de eindtijd van de periode. Als die tijden precies gelijk gehouden zouden worden, dan bestaat er de mogelijkheid dat er wijzigingen gemist worden. Handleiding: Koppelen met Marcom via de REST API 12

14 6 Triggeren van automatische campagnes In MailPlus kunt u ook gebruikmaken van automatische campagnes. Deze automatische campagnes worden ook wel event-driven, event-based of trigger-based campagnes genoemd. Dit betekent dat er naar aanleiding van een gebeurtenis, automatisch een campagne wordt gestart voor een bepaald contact. Binnen een campagne kunnen er diverse stappen worden ingesteld. De meest voor de handliggende stap is het versturen van een e- mail naar het contact waarvoor de campage is gestart. Twee eigenschappen van deze geautomatiseerde campagnes zijn: 1. Ze spelen in op een gebeurtenis (bij of door een contact): Deze gebeurtenis wordt ook wel event of trigger genoemd. 2. Het gaat om één-op-één communicatie: De stappen binnen de campagne gelden alleen voor het contact waarvoor de campagne is gestart. Bijvoorbeeld: één persoon ontvangt een geautomatiseerde mail en niet een grote groep mensen zoals bij een (handmatige) nieuwsbrief. Automatische campagnes in MailPlus kunnen ook vanuit een extern systeem getriggerd worden. Alleen in Marcom Campaigns heeft u de mogelijkheid om zelf automatische campagnes aan te maken. Wilt u meer informatie over het inrichten van campagnes in MailPlus? Neem dan contact op met MailPlus Support of bezoek het Kenniscentrum: Handleiding: Koppelen met Marcom via de REST API 13

15 7 Referrentie REST API methodes 7.1 Methode: Contact toevoegen Met deze methode is het mogelijk om een contact aan MailPlus toe te voegen. Methode POST URL U kunt op twee manieren de content doorgeven: Content-Type: application/xml <?xml version="1.0" encoding="utf-8" standalone="yes"?> <contactrequest> <contact> <externalid>123</externalid> <testgroup>false</testgroup> <properties> <list1> <entry bit="1">true</entry> <entry bit="2">true</entry> </list1> < >test@mailplus.nl</ > <firstname>paul</firstname> </properties> </contact> <purge>false</purge> <update>false</update> </contactrequest> Content-Type: application/json { "update":false, "purge":false, "contact":{ "externalid":"123", "testgroup":false, "properties":{ "list1":[ {"bit":1,"enabled":true}, {"bit":2,"enabled":true}], " ":"test@mailplus.nl", "firstname":"paul" } Handleiding: Koppelen met Marcom via de REST API 14

16 } } Parameters Een ContactRequest bestaat uit: update: boolean Als het contact al bestaat en update is true dan wordt het contact bijgewerkt. Indien false dan komt er een foutmelding terug als het contact al bestaat purge: boolean Indien het contact wordt bijgewerkt dan worden properties die niet zijn gezet geleegd. Contact Een Contact object. Een Contact object bestaat uit: externalid Het unieke id van dit contact. testgroup: boolean Als dit true is dan wordt het contact ook toegevoegd aan de testgroep in MailPlus. Properties De properties die gezet moeten worden. Zie methode voor het ophalen van de properties (7.6) voor meer details. Datumnotatie Geboortedatum en andere datums hebben formaat yyyy-mm-dd. Datum-tijd velden hebben het formaat yyyy-mm-ddthh:mm:ss. De timezone (+02:00) is optioneel. Response Als response geeft de REST API service een http-statuscode 204 terug. Dit betekent dat het contact is succesvol is toegevoegd aan MailPlus. Handleiding: Koppelen met Marcom via de REST API 15

17 7.2 Methode: Contact wijzigen Met deze methode is het mogelijk om een contact in MailPlus te wijzigen. Methode PUT URL U kunt op twee manieren de content doorgeven: Content-Type: application/xml <?xml version="1.0" encoding="utf-8" standalone="yes"?> <contactrequest> <contact> <externalid>123</externalid> <testgroup>false</testgroup> <properties> <list1> <entry bit="1">true</entry> <entry bit="2">true</entry> </list1> < >test@mailplus.nl</ > <firstname>paul</firstname> </properties> </contact> <purge>false</purge> </contactrequest> Content-Type: application/json { } "purge":false, "contact":{ "externalid":"123", "testgroup":false, "properties":{ "list1":[ {"bit":1,"enabled":true}, {"bit":2,"enabled":true}], " ":"test@mailplus.nl", "firstname":"paul" }, } Parameters Een ContactRequest bestaat uit: Handleiding: Koppelen met Marcom via de REST API 16

18 purge: boolean Indien het contact wordt bijgewerkt, dan worden properties die niet zijn gezet geleegd. contact Een Contact object. Een Contact object bestaat uit: externalid Het unieke id van dit contact. testgroup: boolean Als dit true is dan wordt het contact ook toegevoegd aan de testgroep in MailPlus. Properties De properties die gezet moeten worden. Zie methode getavailableproperties voor meer details. Response Als response geeft de REST API service een http-statuscode 204 terug. Dit betekent dat het contact is succesvol is gewijzigd in MailPlus. 7.3 Methode: Contact ophalen Met deze methode is het mogelijk om de gegevens van een contact uit MailPlus op te halen. Methode GET URL Handleiding: Koppelen met Marcom via de REST API 17

19 Parameters Een contact object bestaat uit: externalid: string create Aanmaak datum. Een timestamp in JSON, ISO 8601 formaat in XML. encryptedid: string. Het unieke ID van MailPlus. lastchanged Laatst gewijzigde datum. Een timestamp in JSON, ISO 8601 formaat in XML. temporary: Boolean Geeft aan of het een tijdelijk contact is properties Een lijst van properties van het contact. Wat hier in kan staan is afhankelijk van de call om alle beschikbare properties op te halen (getavailableproperties) channels Alle beschikbare kanalen voor het contact: , DM (direct mail) en SMS. De waarde geeft aan of dit contact beschikbaar is voor het betreffende kanaal) Response Als response geeft de REST API service het contactobject terug met alle gevulde contacteigenschappen. Voorbeeld XML response: <?xml version="1.0" encoding="utf-8" standalone="yes"?> <contact> <channels> <channel name="dm">false</channel> <channel name=" ">true</channel> <channel name="sms">false</channel> </channels> <encryptedid>uz8i5rbsiqtgvke</encryptedid> <externalid>123</externalid> <lastchanged> t10:06:16+02:00</lastchanged> <properties> <lastname>bosselaar</lastname> <freefield1>geachte Heer Bosselaar,</freeField1> <datum1> </datum1> <organisation>mailplus</organisation> <city>amsterdam</city> <permissions> <entry bit="1" description="nieuwsbrief">false</entry> <entry bit="2" description="servicebrief">true</entry> </permissions> </properties> Handleiding: Koppelen met Marcom via de REST API 18

20 <temporary>false</temporary> <testgroup>true</testgroup> </contact> Voorbeeld XML response: { } "externalid" : "123", "created" : , "encryptedid" : "UZ8I5rBSIqtGVKe", "testgroup" : true, "lastchanged" : , "temporary" : false, "properties" : { "lastname" : "Bosselaar", "freefield1" : "Geachte Heer Bosselaar,", "datum1" : " ", "organisation" : "MailPlus", "city" : "Amsterdam", "mailtype" : "direct", " " : "test@mailplus.nl", "permissions": [{"description":"nieuwsbrief","bit":1,"enabled":false}, {"description":"servicebrief","bit":2,"enabled":true}] }, "channels" : [ { "name" : "DM", "value" : false }, { "name" : " ", "value" : true }, { "name" : "SMS", "value" : false } ] 7.4 Methode: Gewijzigde contacten ophalen Met deze methode is het mogelijk om alle contacten uit MailPlus op te halen die in een bepaalde periode zijn gewijzigd. Methode GET URL Handleiding: Koppelen met Marcom via de REST API 19

21 Parameters todate Verplicht. ISO 8601 datum formaat ( T13:14:00+02:00). De timezone (+02:00) is optioneel fromdate Verplicht. ISO 8601 datum formaat ( T13:14:00+02:00). De timezone (+02:00) is optioneel Response Als response geeft de REST API service een lijst van contactobjecten terug met alle gevulde contacteigenschappen. Voorbeeld XML response: <?xml version="1.0" encoding="utf-8" standalone="yes"?> <contacts> <contact> <channels> <channel name="dm">false</channel> <channel name=" ">true</channel> <channel name="sms">false</channel> </channels> <encryptedid>uz8i5rbsiqtgvke</encryptedid> <externalid>123</externalid> <lastchanged> t10:06:16+02:00</lastchanged> <properties> <lastname>bosselaar</lastname> <freefield1>geachte Heer Bosselaar,</freeField1> <datum1> </datum1> <organisation>mailplus</organisation> <city>amsterdam</city> <permissions> <entry bit="1" description="nieuwsbrief">false</entry> <entry bit="2" description="servicebrief">true</entry> </permissions> </properties> <temporary>false</temporary> <testgroup>true</testgroup> </contact> </contacts> Voorbeeld XML response: [ { "externalid" : "123", "created" : , "encryptedid" : "UZ8I5rBSIqtGVKe", "testgroup" : true, "lastchanged" : , "temporary" : false, "properties" : { "lastname" : "Bosselaar", "freefield1" : "Geachte Heer Bosselaar,", Handleiding: Koppelen met Marcom via de REST API 20

22 "datum1" : " ", "organisation" : "MailPlus", "city" : "Amsterdam", "mailtype" : "direct", " " : "test@mailplus.nl", "permissions": [{"description":"nieuwsbrief","bit":1,"enabled":false}, {"description":"servicebrief","bit":2,"enabled":true}] }, "channels" : [ { "name" : "DM", "value" : false }, { "name" : " ", "value" : true }, { "name" : "SMS", "value" : false } ] } ] 7.5 Methode: Gebouncede contacten ophalen Met deze methode is het mogelijk om alle contacten uit MailPlus op te halen die in een bepaalde periode zijn gebounced. Methode GET URL Paramaters todate Verplicht. ISO 8601 datum formaat ( T13:14:00+02:00). De timezone (+02:00) is optioneel fromdate Verplicht. ISO 8601 datum formaat ( T13:14:00+02:00). De timezone (+02:00) is optioneel Een contactbounce bestaat uit: contact Het contact waarvoor de bounce is opgetreden date De dataum wanneer de bounce is opgetreden type HARDBOUNCE of SOFTBOUNCE Handleiding: Koppelen met Marcom via de REST API 21

23 encryptedactid Het encrypted activityid (de mailing) waarvoor de bounce is opgetreden (voor toekomstig gebruik) Response Als response geeft de REST API service een lijst van contactobjecten terug met alle gevulde contacteigenschappen. Voorbeeld XML response: <?xml version="1.0" encoding="utf-8" standalone="yes"?> <contactbounces> <contactbounce> <contact> <channels> <channel name="dm">false</channel> <channel name=" ">true</channel> <channel name="sms">false</channel> </channels> <encryptedid>uz8i5rbsiqtgvke</encryptedid> <externalid>123</externalid> <lastchanged> t10:06:16+02:00</lastchanged> <properties> <lastname>bosselaar</lastname> <freefield1>geachte Heer Bosselaar,</freeField1> <datum1> </datum1> <organisation>mailplus</organisation> <city>amsterdam</city> <permissions> <entry bit="1" description="nieuwsbrief">false</entry> <entry bit="2" description="servicebrief">true</entry> </permissions> </properties> <temporary>false</temporary> <testgroup>true</testgroup> </contact> <date> t13:48:54+01:00</date> <type>hardbounce</type> <encryptedactid>hr92crxz5a5z8an</encryptedactid> </contactbounce> <contactbounce> <contact> <channels> <channel name="dm">false</channel> <channel name=" ">true</channel> <channel name="sms">false</channel> </channels> <encryptedid>uz8i5rbsiqtgvke</encryptedid> <externalid>124</externalid> <lastchanged> t10:06:16+02:00</lastchanged> <properties> <lastname>bosselaar</lastname> <freefield1>geachte Heer Bosselaar,</freeField1> <datum1> </datum1> <organisation>mailplus</organisation> Handleiding: Koppelen met Marcom via de REST API 22

24 <city>amsterdam</city> <permissions> <entry bit="1" description="nieuwsbrief">false</entry> <entry bit="2" description="servicebrief">true</entry> </permissions> </properties> <temporary>false</temporary> <testgroup>true</testgroup> </contact> <date> t13:48:54+01:00</date> <type>softbounce</type> <encryptedactid>hr92crxz5a5z8an</encryptedactid> </contactbounce> </contactbounces> Voorbeeld JSON response: [ { }, { "date" : , "type" : "HARDBOUNCE", "contact" : { "externalid" : "123", "created" : , "encryptedid" : "UZ8I5rBSIqtGVKe", "testgroup" : true, "lastchanged" : , "temporary" : false, "properties" : { "lastname" : "Bosselaar", "freefield1" : "Geachte Heer Bosselaar,", "datum1" : " ", "organisation" : "MailPlus", "city" : "Amsterdam", "mailtype" : "direct", " " : "test@mailplus.nl", "permissions":[ {"description":"nieuwsbrief","bit":1,"enabled":false}, {"description":"servicebrief","bit":2,"enabled":true}] } "channels" : [ { "name" : "DM", "value" : false }, { "name" : " ", "value" : true }, { "name" : "SMS", "value" : false } ] }, "encryptedactid" : "Hr92crXz5A5z8AN" "date" : , "type" : "SOFTBOUNCE", "contact" : { Handleiding: Koppelen met Marcom via de REST API 23