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 Ontdubbeling vindt plaats in MailPlus ......................................... 10
5 WIJZIGINGEN, AFMELDINGEN EN BOUNCES.......................... 11
5.1 Wijzigingen ophalen uit MailPlus Marcom .................................. 11
5.2 Afmeldingen ophalen uit MailPlus Marcom ................................ 12
Handleiding: Koppelen met Marcom via de REST API
2
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 .................................... 20
7.5 Methode: Gebouncede contacten ophalen ................................. 22
7.6 Methode: Contacteigenschappen ophalen ................................. 25
7.7 Methode: Alle campagnes ophalen .............................................. 27
7.8 Methode: Campagne triggeren ..................................................... 28
7.9 Methode: Campagne stoppen ....................................................... 30
8 AANVULLENDE INFORMATIE ................................................... 31
Handleiding: Koppelen met Marcom via de REST API
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”.
Handleiding: Koppelen met Marcom via de REST API
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.
Handleiding: Koppelen met Marcom via de REST API
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.
Handleiding: Koppelen met Marcom via de REST API
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.
Handleiding: Koppelen met Marcom via de REST API
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.
Handleiding: Koppelen met Marcom via de REST API
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.
Handleiding: Koppelen met Marcom via de REST API
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
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.
Handleiding: Koppelen met Marcom via de REST API
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.
Handleiding: Koppelen met Marcom via de REST API
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.
Handleiding: Koppelen met Marcom via de REST API
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
Handleiding: Koppelen met Marcom via de REST API
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
<?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>
<email>[email protected]</email>
<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}],
"email":"[email protected]",
"firstName":"Paul"
}
Handleiding: Koppelen met Marcom via de REST API
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 (hoofdstuk 9) 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
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
<?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>
<email>[email protected]</email>
<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}],
"email":"[email protected]",
"firstName":"Paul"
},
}
}
Parameters
Een ContactRequest bestaat uit:
Handleiding: Koppelen met Marcom via de REST API
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}
Handleiding: Koppelen met Marcom via de REST API
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:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<contact>
<channels>
<channel name="DM">false</channel>
<channel name="EMAIL">true</channel>
<channel name="SMS">false</channel>
</channels>
<encryptedId>UZ8I5rBSIqtGVKe</encryptedId>
<externalId>123</externalId>
<lastChanged>2009-06-26T10:06:16+02:00</lastChanged>
<properties>
<lastName>Bosselaar</lastName>
<freeField1>Geachte Heer Bosselaar,</freeField1>
<datum1>2013-01-22</datum1>
<organisation>MailPlus</organisation>
<city>Amsterdam</city>
<email>[email protected]</email>
<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
<temporary>false</temporary>
<testGroup>true</testGroup>
</contact>
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
} ]
}
Handleiding: Koppelen met Marcom via de REST API
19
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
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:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<contacts>
<contact>
<channels>
<channel name="DM">false</channel>
<channel name="EMAIL">true</channel>
<channel name="SMS">false</channel>
</channels>
<encryptedId>UZ8I5rBSIqtGVKe</encryptedId>
<externalId>123</externalId>
<lastChanged>2009-06-26T10:06:16+02:00</lastChanged>
<properties>
<lastName>Bosselaar</lastName>
<freeField1>Geachte Heer Bosselaar,</freeField1>
<datum1>2013-01-22</datum1>
<organisation>MailPlus</organisation>
<city>Amsterdam</city>
<email>[email protected]</email>
<permissions>
<entry bit="1" description="nieuwsbrief">false</entry>
<entry bit="2" description="servicebrief">true</entry>
</permissions>
</properties>
<temporary>false</temporary>
Handleiding: Koppelen met Marcom via de REST API
20
<testGroup>true</testGroup>
</contact>
</contacts>
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
} ]
} ]
Handleiding: Koppelen met Marcom via de REST API
21
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
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="EMAIL">true</channel>
<channel name="SMS">false</channel>
</channels>
<encryptedId>UZ8I5rBSIqtGVKe</encryptedId>
Handleiding: Koppelen met Marcom via de REST API
22
<externalId>123</externalId>
<lastChanged>2009-06-26T10:06:16+02:00</lastChanged>
<properties>
<lastName>Bosselaar</lastName>
<freeField1>Geachte Heer Bosselaar,</freeField1>
<datum1>2013-01-22</datum1>
<organisation>MailPlus</organisation>
<city>Amsterdam</city>
<email>[email protected]</email>
<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>2013-01-29T13:48:54+01:00</date>
<type>HARDBOUNCE</type>
<encryptedActId>Hr92crXz5A5z8AN</encryptedActId>
</contactBounce>
<contactBounce>
<contact>
<channels>
<channel name="DM">false</channel>
<channel name="EMAIL">true</channel>
<channel name="SMS">false</channel>
</channels>
<encryptedId>UZ8I5rBSIqtGVKe</encryptedId>
<externalId>124</externalId>
<lastChanged>2009-06-26T10:06:16+02:00</lastChanged>
<properties>
<lastName>Bosselaar</lastName>
<freeField1>Geachte Heer Bosselaar,</freeField1>
<datum1>2013-01-22</datum1>
<organisation>MailPlus</organisation>
<city>Amsterdam</city>
<email>[email protected]</email>
<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>2013-01-29T13:48:54+01:00</date>
<type>SOFTBOUNCE</type>
<encryptedActId>Hr92crXz5A5z8AN</encryptedActId>
</contactBounce>
</contactBounces>
Voorbeeld JSON response:
[{
"date" : 1359463734000,
Handleiding: Koppelen met Marcom via de REST API
23
"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" : {
"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",
Handleiding: Koppelen met Marcom via de REST API
24
"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
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:
Handleiding: Koppelen met Marcom via de REST API
25
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<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" />
</entries>
</property>
<property description="Geboortedatum" name="birthday" type="birthdate" />
<property description="valuta1" name="valuta1" type="money" />
</properties>
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
Handleiding: Koppelen met Marcom via de REST API
26
},
{
"bit" : 8,
"description" : "Java, J2EE",
"rank" : 8
} ]
},
{
"name" : "birthday",
"description" : "Geboortedatum",
"type" : "birthdate"
},
{
"name" : "valuta1",
"description" : "valuta1",
"type" : "money"
}
]
7.7
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
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:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
Handleiding: Koppelen met Marcom via de REST API
27
<campaigns>
<campaign>
<active>true</active>
<encryptedId>HE9Bs663Qm</encryptedId>
<name>Welkomstcampagne</name>
<triggers>
<trigger>
<encryptedId>xjcUsjCbsq</encryptedId>
<name>trigger1</name>
</trigger>
<trigger>
<encryptedId>6mC3rAtV4A</encryptedId>
<name>trigger2</name>
</trigger>
</triggers>
</campaign>
</campaigns>
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.
7.8
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}
Handleiding: Koppelen met Marcom via de REST API
28
U kunt op twee manieren doorgeven voor welk contact de campagne
getriggerd moet worden:
Content-Type: application/xml
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<campaignTriggerRequest>
<campaignFields>
<campaignField>
<name>linktosurvey</name>
<value>http://uwexterne systeem.nl/survey</value>
</campaignField>
<campaignField>
<name>vouchercode</name>
<value>12345</value>
</campaignField>
</campaignFields>
<externalContactId>123</externalContactId>
</campaignTriggerRequest>
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.
Handleiding: Koppelen met Marcom via de REST API
29
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.9
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
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<campaignStopRequest>
<externalContactId>123</externalContactId>
</campaignStopRequest>
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.
Handleiding: Koppelen met Marcom via de REST API
30
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/.
Handleiding: Koppelen met Marcom via de REST API
31