Handleiding: Koppelen met Marcom via de REST API

Handleiding:

Koppelen met Marcom via de REST API

Inleiding MailPlus Marcom is een e-mail 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

Inhoudsopgave 1 INTRODUCTIE............................................................................... 4 2 GLOBALE WERKING..................................................................... 5 2.1 Schema van een koppeling ...............................................................5

3 OPZET KOPPELING OP BASIS VAN REST API ............................ 6 3.1 Authenticatie .......................................................................................6 3.1.1

OAuth (Open Authorization) ................................................................... 6

3.1.2

API Key en Secret ...................................................................................... 6

3.1.3

API URL ...................................................................................................... 6

3.2 API methodes .....................................................................................7 3.2.1

XML en JSON ............................................................................................. 7

3.2.2

Standaard methode formaat ................................................................. 7

3.3 Foutafhandeling .................................................................................8 3.3.1

Statuscodes .............................................................................................. 8

3.4 Maak gebruik van een wachtrij ........................................................8 3.4.1

Hoe werkt het wachtrijprincipe? ............................................................ 8

4 CONTACTEN SYNCHRONISEREN ............................................... 9 4.1 Welke contacteigenschappen worden gesynchroniseerd? ..........9 4.2 Contact toevoegen aan MailPlus Marcom ......................................9 4.3 Contact wijzigen in MailPlus Marcom ..............................................9 4.4 Contact verwijderen uit MailPlus Marcom................................... 10 4.5 Contact opzoeken in MailPlus Marcom ....................................... 10 4.6 Ontdubbeling vindt plaats in MailPlus ......................................... 10

5 WIJZIGINGEN, AFMELDINGEN EN BOUNCES.......................... 11 5.1 Wijzigingen ophalen uit MailPlus Marcom .................................. 11


2

5.2 Afmeldingen ophalen uit MailPlus Marcom ................................ 12 5.3 Bounces ophalen uit MailPlus Marcom ....................................... 12

6 TRIGGEREN VAN AUTOMATISCHE CAMPAGNES.................... 13 7 REFERRENTIE REST API METHODES........................................ 14 7.1 Methode: Contact toevoegen ........................................................ 14 7.2 Methode: Contact wijzigen ............................................................ 16 7.3 Methode: Contact ophalen ............................................................ 17 7.4 Methode: Gewijzigde contacten ophalen .................................... 19 7.5 Methode: Gebouncede contacten ophalen ................................. 21 7.6 Methode: Contacteigenschappen ophalen ................................. 24 7.7 Methode: Contacten opzoeken op basis van eigenschap ......... 27 7.8 Methode: Alle campagnes ophalen .............................................. 28 7.9 Methode: Campagne triggeren ..................................................... 30 7.10 Methode: Campagne stoppen ....................................................... 31

8 AANVULLENDE INFORMATIE ................................................... 32


3

1

Introductie MailPlus Marcom kent 2 productversies: 1) MailPlus Marcom Mailer MailPlus Marcom Mailer is bedoeld voor de praktische e-mail marketing professional. Naast het opstellen en versturen van e-mails 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 e-mails, 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 e-mail marketing oplossing die ondermeer e-mail marketing automation mogelijk maakt. Hiermee kunt u event-driven e-mail 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”.


4

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 e-mail wordt verstuurd vanuit MailPlus Marcom naar een contactpersoon die van prospect naar klant is omgezet. Ook dit wordt gesymboliseerd door de pijl naar rechts.


5

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.

3.1.1

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.

3.1.2

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.

3.1.3

API URL Alle REST API aanroepen hebben de volgende URL als basis: https://restapi.mailplus.nl/integrationservice-1.1.0/

N.B.: Deze URL werkt alleen als er een methode op de juiste manier wordt aangesproken.


6

3.2

API methodes

3.2.1

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”.

3.2.2

Standaard methode formaat Het standaard methode formaat van alle REST API verzoeken is: METHOD https://restapi.mailplus.nl/integrationservice1.1.0/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.


7

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.

3.3.1

Statuscodes MailPlus geeft één van de volgende drie statuscodes terug bij een fout:   

3.4

400: Bad request A given value was invalid (e.g. wrong e-mail 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)

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.

3.4.1

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.


8

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, E-mailadres, 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 e-mailing.

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.


9

4.4

Contact verwijderen uit MailPlus Marcom Het is niet mogelijk om contacten te verwijderen uit MailPlus Marcom. Zo blijft de historie van e-mailings 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 emailings 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 emailadres. 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.


10

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 e-mailing die hun gegevens wijzigen op een landingspagina in MailPlus Marcom. Ontvangers van een e-mailing die zichzelf afmelden. Ontvangers van een e-mailing waarvan het e-mailadres 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 e-mailing 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 e-mailadres 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 e-mailadres 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.


11

5.2

Afmeldingen ophalen uit MailPlus Marcom Elke e-mailing die wordt verstuurd vanuit MailPlus Marcom heeft een link in het bericht opgenomen waarmee de ontvanger zichzelf kan afmelden voor toekomstige e-mailings 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 e-mailing die wordt gedaan in MailPlus Marcom kunnen er bounces ontstaan. De e-mail 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 e-mailadres van het desbetreffende ontvanger niet in orde. Het kan gaan om een typefout of het e-mailadres 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.


12

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 email 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: http://kennis.mailplus.nl/toepassing/inzet-van-een-automatischecampagne/?lang=nl


13

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 https://restapi.mailplus.nl/integrationservice-1.1.0/contact U kunt op twee manieren de content doorgeven: Content-Type: application/xml <externalId>123 false <properties> <list1> <entry bit="1">true <entry bit="2">true <email>[email protected] Paul false false

Content-Type: application/json { "update":false, "purge":false, "contact":{ "externalId":"123", "testGroup":false, "properties":{ "list1":[ {"bit":1,"enabled":true}, {"bit":2,"enabled":true}], "email":"[email protected]", "firstName":"Paul" }


14

} }

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.


15

7.2

Methode: Contact wijzigen Met deze methode is het mogelijk om een contact in MailPlus te wijzigen. Methode PUT URL https://restapi.mailplus.nl/integrationservice-1.1.0/contact/{externalId} U kunt op twee manieren de content doorgeven: Content-Type: application/xml <externalId>123 false <properties> <list1> <entry bit="1">true <entry bit="2">true <email>[email protected] Paul false

Content-Type: application/json { "purge":false, "contact":{ "externalId":"123", "testGroup":false, "properties":{ "list1":[ {"bit":1,"enabled":true}, {"bit":2,"enabled":true}], "email":"[email protected]", "firstName":"Paul" }, } }

Parameters Een ContactRequest bestaat uit:


16

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 https://restapi.mailplus.nl/integrationservice-1.1.0/contact/{externalId}


17

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: “EMAIL”, “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: false true false <encryptedId>UZ8I5rBSIqtGVKe <externalId>123 2009-06-26T10:06:16+02:00 <properties> Bosselaar Geachte Heer Bosselaar, 2013-01-22 MailPlus Amsterdam <email>[email protected] <entry bit="1" description="nieuwsbrief">false <entry bit="2" description="servicebrief">true


18

false true

Voorbeeld XML response: { "externalId" : "123", "created" : 1246003576000, "encryptedId" : "UZ8I5rBSIqtGVKe", "testGroup" : true, "lastChanged" : 1246003576000, "temporary" : false, "properties" : { "lastName" : "Bosselaar", "freeField1" : "Geachte Heer Bosselaar,", "datum1" : "2013-01-22", "organisation" : "MailPlus", "city" : "Amsterdam", "mailType" : "direct", "email" : "[email protected]", "permissions": [{"description":"nieuwsbrief","bit":1,"enabled":false}, {"description":"servicebrief","bit":2,"enabled":true}] }, "channels" : [ { "name" : "DM", "value" : false }, { "name" : "EMAIL", "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 https://restapi.mailplus.nl/integrationservice-1.1.0/contact/updates/list


19

Parameters 



toDate Verplicht. ISO 8601 datum formaat (2013-01-01T13:14:00+02:00). De timezone (+02:00) is optioneel fromDate Verplicht. ISO 8601 datum formaat (2013-01-01T13: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: false true false <encryptedId>UZ8I5rBSIqtGVKe <externalId>123 2009-06-26T10:06:16+02:00 <properties> Bosselaar Geachte Heer Bosselaar, 2013-01-22 MailPlus Amsterdam <email>[email protected] <entry bit="1" description="nieuwsbrief">false <entry bit="2" description="servicebrief">true false true

Voorbeeld XML response: [ { "externalId" : "123", "created" : 1246003576000, "encryptedId" : "UZ8I5rBSIqtGVKe", "testGroup" : true, "lastChanged" : 1246003576000, "temporary" : false, "properties" : { "lastName" : "Bosselaar", "freeField1" : "Geachte Heer Bosselaar,",


20

"datum1" : "2013-01-22", "organisation" : "MailPlus", "city" : "Amsterdam", "mailType" : "direct", "email" : "[email protected]", "permissions": [{"description":"nieuwsbrief","bit":1,"enabled":false}, {"description":"servicebrief","bit":2,"enabled":true}] }, "channels" : [ { "name" : "DM", "value" : false }, { "name" : "EMAIL", "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 https://restapi.mailplus.nl/integrationservice-1.1.0/contact/bounces/list Paramaters toDate Verplicht. ISO 8601 datum formaat (2013-01-01T13:14:00+02:00). De timezone (+02:00) is optioneel  fromDate Verplicht. ISO 8601 datum formaat (2013-01-01T13: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


21



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: false true false <encryptedId>UZ8I5rBSIqtGVKe <externalId>123 2009-06-26T10:06:16+02:00 <properties> Bosselaar Geachte Heer Bosselaar, 2013-01-22 MailPlus Amsterdam <email>[email protected] <entry bit="1" description="nieuwsbrief">false <entry bit="2" description="servicebrief">true false true 2013-01-29T13:48:54+01:00 HARDBOUNCE <encryptedActId>Hr92crXz5A5z8AN false true false <encryptedId>UZ8I5rBSIqtGVKe <externalId>124 2009-06-26T10:06:16+02:00 <properties> Bosselaar Geachte Heer Bosselaar, 2013-01-22 MailPlus


22

Amsterdam <email>[email protected] <entry bit="1" description="nieuwsbrief">false <entry bit="2" description="servicebrief">true false true 2013-01-29T13:48:54+01:00 SOFTBOUNCE <encryptedActId>Hr92crXz5A5z8AN

Voorbeeld JSON response: [{ "date" : 1359463734000, "type" : "HARDBOUNCE", "contact" : { "externalId" : "123", "created" : 1246003576000, "encryptedId" : "UZ8I5rBSIqtGVKe", "testGroup" : true, "lastChanged" : 1246003576000, "temporary" : false, "properties" : { "lastName" : "Bosselaar", "freeField1" : "Geachte Heer Bosselaar,", "datum1" : "2013-01-22", "organisation" : "MailPlus", "city" : "Amsterdam", "mailType" : "direct", "email" : "[email protected]", "permissions":[ {"description":"nieuwsbrief","bit":1,"enabled":false}, {"description":"servicebrief","bit":2,"enabled":true}] } "channels" : [ { "name" : "DM", "value" : false }, { "name" : "EMAIL", "value" : true }, { "name" : "SMS", "value" : false }] }, "encryptedActId" : "Hr92crXz5A5z8AN" }, { "date" : 1359463734000, "type" : "SOFTBOUNCE", "contact" : {


23

"externalId" : "124", "created" : null, "encryptedId" : "UZ8I5rBSIqtGVKe", "testGroup" : true, "lastChanged" : 1246003576000, "temporary" : false, "properties" : { "lastName" : "Bosselaar", "freeField1" : "Geachte Heer Bosselaar,", "datum1" : "2013-01-22", "organisation" : "MailPlus", "city" : "Amsterdam", "mailType" : "direct", "email" : "[email protected]", "permissions":[ {"description":"nieuwsbrief","bit":1,"enabled":false}, {"description":"servicebrief","bit":2,"enabled":true}] }, "channels" : [ { "name" : "DM", "value" : false }, { "name" : "EMAIL", "value" : true }, { "name" : "SMS", "value" : false }] }, "encryptedActId" : "Hr92crXz5A5z8AN" }]

7.6

Methode: Contacteigenschappen ophalen Met deze methode is het mogelijk om een lijst van contacteigenschappen (properties) uit MailPlus op te halen. Met deze methode bent u in staat om te weten met welke eigenschappen u een contact kunt toevoegen aan MailPlus. Methode GET URL https://restapi.mailplus.nl/integrationservice-1.1.0/contact/properties/list


24

Parameters Een property bestaat uit: 







name De naam van de property zoals deze gebruikt moet worden in andere calls description De omschrijving van de property zoals de MailPlus gebruiker deze in MailPlus ziet type Het type van de property (string, set, date, birthdate, email, mobNr, gender, valuta, number) entries Dit is alleen aanwezig indien het type "set" is. Hierin bevindt zich een lijst van de verschillende opties uit de set. Deze bestaat uit een bit en een description. De bit is de unieke identifier die gebruikt dient te worden bij een insert of een update van een contact.

Response Als response geeft de REST API service een lijst van properties terug. Voorbeeld XML response: <properties> <property description="E-mailadres" name="email" type="email" /> <property description="Voornaam" name="firstName" type="string" /> <property description="Achternaam" name="lastName" type="string" /> <property description="Geslacht" name="gender" type="gender" /> <property description="Mobiel nr." name="mobileNumber" type="mobNr" /> <property description="Opties" name="list1" type="set"> <entries> <entry bit="1" description="SAP" rank="1" /> <entry bit="2" description="VM ware" rank="2" /> <entry bit="4" description="Coolgen" rank="4" /> <entry bit="8" description="Java, J2EE" rank="8" /> <property description="Geboortedatum" name="birthday" type="birthdate" /> <property description="valuta1" name="valuta1" type="money" />


25

Voorbeeld XML response: [ { "name" : "email", "description" : "E-mailadres", "type" : "email" }, { "name" : "firstName", "description" : "Voornaam", "type" : "string" }, { "name" : "lastName", "description" : "entriesAchternaam", "type" : "string" },{ "name" : "gender", "description" : "Geslacht", "type" : "gender" }, { "name" : "mobileNumber", "description" : "Mobiel nr.", "type" : "mobNr" }, { "name" : "list1", "description" : "Opties", "type" : "set", "entries" : [ { "bit" : 1, "description" : "SAP", "rank" : 1 }, { "bit" : 2, "description" : "VM ware", "rank" : 2 }, { "bit" : 4, "description" : "Coolgen", "rank" : 4 }, { "bit" : 8, "description" : "Java, J2EE", "rank" : 8 } ] }, { "name" : "birthday", "description" : "Geboortedatum", "type" : "birthdate" }, { "name" : "valuta1", "description" : "valuta1", "type" : "money" } ]


26

7.7

Methode: Contacten opzoeken op basis van eigenschap Met deze methode is het mogelijk om alle contacten uit MailPlus op te halen op basis van een bepaalde eigenschap of op basis van een combinatie van meerdere eigenschappen. Methode GET URL https://restapi.mailplus.nl/integrationservice-1.1.0/contact/search Parameters 

Eén of meerdere eigenschappen Property=value. Bijvoorbeeld “[email protected]”. Gebruik een andere call (GET properties/list) om te weten op basis van welke eigenschappen er contacten gevonden kunnen worden.

Response Als response geeft de REST API service een lijst van contactobjecten terug met alle gevulde contacteigenschappen. Voorbeeld XML response: false true false <encryptedId>UZ8I5rBSIqtGVKe <externalId>123 2009-06-26T10:06:16+02:00 <properties> Bosselaar 2013-01-22 MailPlus Amsterdam <email>[email protected] <entry bit="1" description="nieuwsbrief">false <entry bit="2" description="servicebrief">true false true


27

Voorbeeld XML response: [ { "externalId" : "123", "created" : 1246003576000, "encryptedId" : "UZ8I5rBSIqtGVKe", "testGroup" : true, "lastChanged" : 1246003576000, "temporary" : false, "properties" : { "lastName" : "Bosselaar", "datum1" : "2013-01-22", "organisation" : "MailPlus", "city" : "Amsterdam", "mailType" : "direct", "email" : "[email protected]", "permissions": [{"description":"nieuwsbrief","bit":1,"enabled":false}, {"description":"servicebrief","bit":2,"enabled":true}] }, "channels" : [ { "name" : "DM", "value" : false }, { "name" : "EMAIL", "value" : true }, { "name" : "SMS", "value" : false } ] } ]

7.8

Methode: Alle campagnes ophalen Met deze methode is het mogelijk om alle campagnes van een MailPlusaccount op te halen. Methode GET URL https://restapi.mailplus.nl/integrationservice-1.1.0/campaign/list Response Als response geeft de REST API service een lijst terug van alle campagnes van het MailPlus-account. Per opgehaalde campagne krijg je de volgende gegevens terug:  

encryptedId van de campagne (om de campagne op enig moment te kunnen stoppen indien nodig) Naam van de campagne


28



Alle externe triggers van de campagne, waarbij per trigger: o Naam van de trigger o encryptedId van de trigger (om de campagne op enig moment te kunnen triggeren)

Voorbeeld XML: true <encryptedId>HE9Bs663Qm Welkomstcampagne <encryptedId>xjcUsjCbsq trigger1 <encryptedId>6mC3rAtV4A trigger2

Voorbeeld JSON: [{ "encryptedId":" HE9Bs663Qm", "name":" Welkomstcampagne", "active":true, "triggers":[ {"encryptedId":"xjcUsjCbsq","name":"trigger 1"}, {"encryptedId":"6mC3rAtV4A","name":"trigger 2"} ] }]

Bijzonderheden Ook inactieve campagnes kunnen worden opgehaald, zodat u deze alvast kunt instellen in het externe systeem. Alleen als er externe triggers in de campagne zijn geconfigureerd, krijg je deze mee in de response. Er is meestal maar een externe trigger per campagne ingesteld, maar het kunnen er meer zijn.


29

7.9

Methode: Campagne triggeren Met deze methode is het mogelijk om een MailPlus-campagne te triggeren voor een bepaald contact. Methode POST URL https://restapi.mailplus.nl/integrationservice1.1.0/campaign/trigger/{encryptedId} U kunt op twee manieren doorgeven voor welk contact de campagne getriggerd moet worden: Content-Type: application/xml linktosurvey http://uwexterne systeem.nl/survey vouchercode 12345 <externalContactId>123

Content-Type: application/json { "campaignFields":[ {"name":"linktosurvey","value":"http://uwexterne systeem.nl/survey"}, {"name":"vouchercode","value":"12345"} ], "externalContactId":"123" }

Parameters Het encryptedId is het ID van de campagnetrigger. Niet te verwarren met het ID van de campagne zelf.


30

Response Als response geeft de REST API service een http-statuscode “204” terug. Dit betekent dat de campagne succesvol is getriggerd voor het contact in MailPlus.

7.10

Methode: Campagne stoppen Met deze methode is het mogelijk om een MailPlus-campagne te stoppen voor een bepaald contact. Methode POST URL https://restapi.mailplus.nl/integrationservice1.1.0/campaign/{encryptedId}/stop U kunt op twee manieren doorgeven voor welk contact de campagne gestopt moet worden: Content-Type: application/xml <externalContactId>123

Content-Type: application/json {"externalContactId":"123"}

Parameters Het encryptedId in de URL is het ID van de campagne. Niet te verwarren met het ID van de campagnetrigger. Response Als response geeft de REST API service een http-statuscode “204” terug. Dit betekent dat de campagne succesvol is gestopt voor het contact in MailPlus.


31

8

Aanvullende informatie Voor diverse externe (CRM-) systemen hoeft u niet zelf een koppeling met MailPlus te ontwikkelen. Die heeft MailPlus al voor u laten ontwikkelen in de vorm van standaard connectors.

Wilt u weten of de door u gewenste connector daarbij zit? Bezoek dan onze website: http://www.mailplus.nl/integraties/.


32

Handleiding: Koppelen met Marcom via de REST API

Recommend Documents