Handleiding Webwinkel koppelen met MailPlus ecom via de REST API Deze handleiding is in te zetten voor ecom Business en Enterprise
Inleiding MailPlus ecom is een e-mail marketing oplossing voor webwinkels. Met MailPlus ecom kan de marketeer eenvoudig professionele nieuwsbrieven opstellen en versturen met productinformatie uit de webwinkel. Het is ook mogelijk om vanuit de webwinkel automatische geavanceerde event-driven marketingcampagnes te aan te sturen naar aanleiding van een gebeurtenis in de webwinkel. Denk daarbij aan een welkomst e-mail bij een nieuwsbriefinschrijving, een automatische e-mail als iemand zijn winkelwagen achterlaat zonder afgerekend te hebben, product review-campagnes, et cetera. In de rapportage van elke verstuurde nieuwsbrief is terug te zien wat de effectiviteit is geweest en hoeveel omzet ermee is gegenereerd. MailPlus ecom is bedoeld om gekoppeld te zijn met een webwinkel. Zowel contacten als producten kunnen real-time vanuit de webwinkel worden gesynchroniseerd naar MailPlus ecom. Zo kan de marketeer binnen een handomdraai via een gebruiksvriendelijke editor een productennieuwsbrief creëren. Omdat de contacten uit de webshop door de synchronisatie al in MailPlus staan, kan de nieuwsbrief op elk gewenst moment verstuurd worden zonder extra handelingen van de marketeer. Voor een goede koppeling tussen de webwinkel en MailPlus ecom is een REST API beschikbaar. Er dient hiervoor wel aan webwinkelzijde een plug in ontwikkeld te worden die met deze REST API communiceert. Dit document beschrijft wat een ontwikkelaar moet weten om zo n plug in te maken. Het is niet altijd nodig om zelf een plug in te ontwikkelen. Voor sommige webwinkelsystemen, zoals Magento, is een gratis connector beschikbaar.
Inhoudsopgave Introductie... 1 1 Globale werking van de koppeling... 2 1.1 Schema van de koppeling... 2 2 Opzet koppeling op basis van REST API... 4 2.1 OAuth (Open Authorization)... 4 2.2 API Key en Secret... 4 2.3 API URL... 5 2.4 API Methodes... 5 2.5 Foutafhandeling... 6 2.6 Maak gebruik van een wachtrij... 7 3 Contacten synchroniseren... 9 3.1 Welke contacteigenschappen worden gesynchroniseerd?... 9 3.2 Permissies... 9 3.3 Contact toevoegen aan Mailplus ecom... 10 3.4 Contact wijzingen in MailPlus ecom... 10 3.5 Contact verwijderen uit MailPlus ecom... 10 4 Wijzigingen, afmeldingen en bounces... 11 4.1 Wijzigingen ophalen uit MailPlus ecom... 11 4.2 Afmeldingen ophalen uit MailPlus ecom... 12 4.3 Bounces ophalen uit MailPlus ecom... 12 5 Producten Synchroniseren... 14 5.1 Producteigenschappen... 15 5.2 Product toevoegen aan MailPlus ecom... 16 5.3 Product wijzigen in MailPlus ecom... 16 5.4 Product verwijderen uit MailPlus ecom... 16 6 Orders Synchroniseren... 17 6.1 Ordereigenschappen... 17 6.2 Order toevoegen aan MailPlus ecom... 17 6.3 Order wijzigen in MailPlus ecom... 17 6.4 Order verwijderen uit MailPlus ecom... 17
7 Conversie doorgeven... 18 7.1 Conversie winkelwagen aangemaakt doorgeven... 19 7.2 Conversie bestelling geplaatst doorgeven... 19 8 Automatische campagnes... 21 8.1 Welkomstcampagne bij aanmelding nieuwsbrief... 22 8.2 Verlaten winkelwagen campagne... 22 8.3 Product review campagne... 23 9 Referentie REST API methodes... 24 9.1 Methode: Contact toevoegen... 24 9.2 Methode: Contact wijzigen... 25 9.3 Methode: Contact ophalen... 27 9.4 Methode: Gewijzigde contacten ophalen... 29 9.5 Methode: Gebouncede contacten ophalen... 31 9.6 Methode: Contacteigenschappen ophalen... 34 9.7 Methode: Product toevoegen... 36 9.8 Methode: Product wijzigen... 39 9.9 Methode: Product verwijderen... 40 9.10 Methode: Product ophalen... 40 9.11 Methode: Order toevoegen... 42 9.12 Methode: Order wijzigen... 43 9.13 Methode: Order verwijderen... 44 9.14 Methode: Winkelwagen aangemaakt doorgeven... 45 9.15 Methode: Winkelwagen geconverteerd doorgeven... 45 9.16 Methode: Alle campagnes ophalen... 47 9.17 Methode: Campagne triggeren... 48 9.18 Methode: Campagne stoppen... 49 10 Aanvullende informatie... 51
Introductie MailPlus ecom kent 2 productversies: 1) MailPlus ecom Business MailPlus ecom Business is bedoeld voor de professionele webwinkelier die naast een productennieuwsbrief ook diverse automatische, eventdriven marketingcampagnes verstuurt. Binnen MailPlus ecom Business zijn diverse kant-en-klare automatische campagnes beschikbaar om extra omzet te genereren: Welkom nieuwsbrief-, Verlaten winkelwagen-, Product review-, Win back- en Verjaardagscampagne. 2) MailPlus Enterprise MailPlus ecom Enterprise is een stabiele, schaalbare e-mail marketing oplossing die volledig kan integreren. Naast diverse kant-en-klare automatische campagnes, kan de marketeer ook eigen campagnes creëren. Daarnaast biedt MailPlus ecom Enteprise geavanceerde segmentatiemogelijkheden, zoals Nieuwsbrief-Op-Maat waarbij (delen van de) reguliere nieuwsbrief zijn afgestemd op de individuele ontvanger op basis van zijn of haar interesses of op basis van zijn of haar gedrag in de webwinkel. In dit document beschrijft hoe een ontwikkelaar een koppeling kan ontwikkelen tussen een webwinkel en MailPlus ecom. In hoofdstuk 1 wordt eerst ingegaan op de globale werking van de koppeling. Hoofdstuk 2 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, Producten synchroniseren, Conversie doorgeven en Campagnes triggeren. Hoofdstuk 9 is een Referentie van alle REST API methodes. Het document wordt beëindigd met een hoofdstuk Aanvullende informatie. 1
1 Globale werking van de koppeling Een koppeling tussen een webwinkel en MailPlus ecom kan uit grofweg uit 5 onderdelen bestaan: Real-time synchronisatie van contactgegevens Real-time synchronisatie van productgegevens Real-time synchronisatie van ordergegevens Doorgeven van conversie in de webwinkel naar aanleiding van de nieuwsbrief Triggeren van automatische event-driven marketingcampagnes 1.1 Schema van een koppeling In bovenstaand schema is te zien dat MailPlus ecom beschikt over een REST API. Hiermee wordt de koppeling gelegd. Daarvoor is aan webwinkelzijde een stukje software nodig. We noemen dit een connector of een plug in. Dit document beschrijft hoe een ontwikkelaar zo n connector kan ontwikkelen. De contacten, producten en orders in de database van de webwinkel worden door de connector real-time met MailPlus ecom synchroon gehouden. Dit wordt gesymboliseerd door de pijl naar rechts. 2
De webwinkel is daarbij het leidende systeem. Er is daarbij één uitzondering. Dat is wanneer ontvangers van een nieuwsbrief hun gegevens wijzigen op een landingspagina in MailPlus ecom. De gewijzigde contactgegevens worden automatisch weer teruggestuurd en doorgevoerd in de webwinkel. Dat is de pijl naar links in het schema. De connector geeft daarnaast direct een signaal door aan MailPlus ecom op het moment dat er conversie heeft plaatsgevonden in de webwinkel naar aanleiding van de nieuwsbrief. Dit wordt gesymboliseerd door de pijl naar rechts. Ten slotte, kan de webwinkel event-driven marketing campagnes aansturen op het moment dat er een gebeurtenis plaatsvindt in de webwinkel. Zo kan de webwinkel ervoor zorgen dat er een e-mail wordt verstuurd vanuit MailPlus ecom naar iemand die zijn winkelwagen heeft achtergelaten zonder de bestelling te hebben afgerond. Ook dit wordt gesymboliseerd door de pijl naar rechts. 3
2 Opzet koppeling op basis van REST API Het is van belang dat de service kan verifiëren of de API aanroepen wel van de juiste bron (uw webshop) komen. Daarom vindt er bij bij het gebruik van de REST API service bij iedere aanroep authenticatie plaats. OAuth (Open Authorization) 2.1 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 2.2 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 de webshop waarmee MailPlus gekoppeld wordt. Ga hiervoor naar het vierde tabblad MailPlus Instellingen op de startpagina. Hier kunt een nieuwe autorisatie aanmaken. U dient een autorisatie een naam te geven. Het is daarbij handig om een logische naam te geven. Bijvoorbeeld de naam van de webshop. Als u de autorisatie heeft aangemaakt, toont MailPlus de Key en Secret die u nodig heeft in de webshop. 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. 4
2.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. 2.4 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 https://restapi.mailplus.nl/integrationservice-1.1.0/ transaction?parameters Methode GET, POST, PUT, of DELETE Transaction De API service die u wilt aanspreken, bijvoorbeeld product. 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. 5
Response De response van alle REST API aanroepen is JSON of XML. U kunt zelf bepalen wat u het prettigst vindt werken. 2.5 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. Statuscode MailPlus geeft één van de volgende drie statuscodes terug bij een fout: 404: badrequest A given value was invalid (e.g. wrong e-mail address 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) Hieronder enkele voorbeelden. Voorbeeld 1: Verkeerde paramater meegestuurd Hieronder een voorbeeld van een foutmelding die u terugkrijgt indien u een verkeerde parameter heeft meegestuurd. In dit geval een verkeerde productprijs. XML <?xml version= 1.0 encoding= UTF-8 standalone= yes?> <errorresponse> <errortype>invalid_params</errortype> <message>price invalid</message> </errorresponse> 6
JSON { errortype : INVALID_PARAMS, message : price invalid } Voorbeeld 2: Product bestaat niet Hieronder een voorbeeld van een foutmelding die u terugkrijgt indien u een product probeert te wijzigen of te verwijderen waarvan het productid niet bestaat. De response code = 404. XML <?xml version= 1.0 encoding= UTF-8 standalone= yes?> <errorresponse> <errortype>product_notfound</errortype> <message>product not found with externalproductid: test1355147847647123</message> </errorresponse> JSON { errortype : PRODUCT_NOTFOUND, message : product not found with externalproductid: test1355147847647123 } 2.6 Maak gebruik van een wachtrij Er kan altijd iets mis zijn met de verbinding tussen de webwinkel en MailPlus ecom. Dit kan verschillende oorzaken hebben. Bijvoorbeeld omdat de server waar de webwinkel 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 de webwinkel en MailPlus ecom, dan moet de aanroep automatisch worden opgeslagen in een 7
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 de webwinkel. 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
3 Contacten synchroniseren De webwinkel is het leidende systeem voor contactgegevens. Nieuwe inschrijvingen voor de nieuwsbrief of nieuwe klanten ontstaan in de webwinkel. Voor een marketeer die MailPlus ecom gebruikt voor het versturen van nieuwsbrieven is het fijn als het contactenbestand altijd up-to-date is op het moment dat de nieuwsbrief de deur uit moet. Daarom is het wenselijk om contacten (near-) real-time te synchoniseren naar MailPlus ecom. 3.1 Welke contacteigenschappen worden gesynchroniseerd? Er zijn een aantal contactvelden standaard beschikbaar in MailPlus ecom, 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. Twee contactvelden verdienen speciale aandacht: 1. firstpurchasedate 2. lastpurchasedate Op basis van deze gegevens kunnen er automatische campagnes ingesteld worden in MailPlus ecom. Ook deze gegevens worden gevoed door de webwinkel. De firstpurchasedate wordt eenmalig gezet op het moment dat iemand voor de allereerste keer een bestelling plaatst. De lastpurchasedate dient elke keer door de webwinkel aangepast te worden op het moment dat iemand een bestelling plaatst. 3.2 Permissies In MailPlus ecom wordt gebruikgemaakt van permissies. Dat wil zeggen dat een contact zich kan inschrijven of juist afmelden voor een specifieke e-mailing. Standaard bestaan er twee permissies in MailPlus ecom, te weten: Nieuwsbrief en Speciale acties voor klanten. De 9
permissie Nieuwsbrief spreekt voor zich. De permissie Speciale acties voor klanten is bedoeld voor de event-driven marketing campagnes. Om een voorbeeld te geven, iemand die zich afmeldt voor Product review mailings, wil misschien best de nieuwsbrief blijven ontvangen. Door gebruik te maken van permissies is dat mogelijk. 3.3 Contact toevoegen aan MailPlus ecom Als er een nieuw contact ontstaat in de webwinkel, dan kan deze direct worden ingeschoten in MailPlus ecom via de REST API. Nieuwe contacten kunnen ontstaan door nieuwsbriefinschrijvingen of door klantregistraties. Het kan ook een combinatie van beide zijn. 3.4 Contact wijzigen in MailPlus ecom In de webwinkel kunnen er diverse plekken zijn waar contactgegevens wijzigen. Bijvoorbeeld door de webwinkelier in het backend of door contacten (klanten) zelf op een profielpagina als zij ingelogd zijn in het frontend van de webwinkel. Zodra er een contactwijziging plaatsvindt, dient de wijziging direct doorgegeven te worden aan MailPlus ecom. Er zijn twee methodes om contacten in MailPlus ecom 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 de webwinkel niet te onthouden of een contact mogelijk al eens eerder is ingeschoten. De andere methode is specifiek voor het wijzigen van een contact. 3.5 Contact verwijderen uit MailPlus ecom Het is niet mogelijk om contacten te verwijderen uit MailPlus ecom. 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 ecom om te voorkomen dat iemand ten onrechte alsnog nieuwe e-mailings ontvangt. Als een contact wordt verwijderd in de webwinkel, dan dienen alle permissies van dat contact uitgezet te worden in MailPlus ecom door het contact te wijzigen. 10
4 Wijzigingen, afmeldingen en bounces In principe is de webwinkel leidend voor alle contactgegevens. Maar er zijn een paar uitzonderingen voor zaken die plaatsvinden in MailPlus ecom. Het gaat om de volgende zaken: Ontvangers van een e-mailing die hun gegevens wijzigen op een landingspagina in MailPlus ecom. 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 de webwinkel om de gegevens in de webwinkel up-to-date te houden. 4.1 Wijzingen ophalen uit MailPlus ecom Elke e-mailing die wordt verstuurd vanuit MailPlus ecom heeft een link in het bericht opgenomen waarmee de ontvanger zijn of haar contactgegevens kan wijzigen op een landingspagina in MailPlus ecom. In principe kunnen dat alle gegevens zijn die bekend zijn van dat contact in MailPlus ecom. Als het e-mailadres tevens wordt gebruikt in de webwinkel als gebruikersnaam om in te loggen als klant, dan is het raadzaam om dit veld niet op te nemen in het formulier op de 11
profielwijzigpagina in MailPlus ecom. Als ontvangers hun e-mailadres willen wijzigen, dan dienen ze dat te doen in de webshop. Contactwijzigingen uit MailPlus ecom dienen periodiek te worden opgehaald door de webwinkel. Bijvoorbeeld één keer per uur of één keer per dag. Bij de methode om contactgegevens op te halen dient de webwinkel 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. 4.2 Afmeldingen ophalen uit MailPlus ecom Elke e-mailing die wordt verstuurd vanuit MailPlus ecom 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 de webwinkel. 4.3 Bounces ophalen uit MailPlus ecom Bij iedere e-mailing die wordt gedaan in MailPlus ecom kunnen er bounces ontstaan. De e-mail is dan niet bij de desbetreffende ontvanger aangekomen. 12
Bij een soft bounce is er sprake van een tijdelijke situatie. Hier hoeft de webwinkel 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 de webwinkel opgehaald te worden uit MailPlus ecom. In de eerste plaats om het bestand in de webwinkel 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 de webwinkel. Ook bij de methode om bounces op te halen dient de webwinkel 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. 13
5 Producten Synchroniseren In MailPlus ecom kan een marketeer eenvoudig producten uit de webwinkel plaatsen in een nieuwsbrief. Producten zijn met een simpele klik in de juiste opmaak in de nieuwsbrief zonder dat daar technische kennis voor nodig is. Daarvoor is het wel nodig om alle producten uit de webwinkel real-time te synchroniseren naar MailPlus ecom. De producten uit de webwinkel verschijnen in een popup binnen de editor. Van daaruit kunnen de producten met een simpele klik in de nieuwsbrief geplaatst worden. 14
5.1 Producteigenschappen De volgende eigenschappen van een product kunnen worden ingeschoten in MailPlus ecom. Brand (merknaam) Productnaam Omschrijving (kort) VanPrijs (de prijs zonder korting) Prijs Categorie Url naar de productafbeelding in de webwinkel (afmeting 1) Url naar de productafbeelding in de webwinkel (afmeting 2) Url van de rating-afbeelding (hoeft niet gebruikt te worden) Voorraad (Goed of Beperkt) Specificaties (een lijst van één of meerdere producteigenschappen) Cijfer productwaardering Taal van het product Link naar de productpagina in de webwinkel Link naar de review-pagina van het product Link die het product toevoegt aan de winkelwagen Gtin Sku 15
5.2 Product toevoegen aan MailPlus ecom Als er een nieuw product ontstaat in de webwinkel, dan dient deze direct te worden ingeschoten in MailPlus ecom via de REST API. 5.3 Product wijzigen in MailPlus ecom Als een product wordt gewijzigd in de webwinkel, dan dient deze wijziging direct ook in MailPlus ecom te worden doorgevoerd. Houd er rekening mee dat als een product wordt gereviewed door een consument in de webwinkel, dat dat ook een productwijziging betekent, namelijk een wijziging van de rating-waarde. 5.4 Product verwijderen uit MailPlus ecom Als een product wordt verwijderd in de webwinkel, dan dient deze direct ook uit MailPlus ecom te worden verwijderd. 16
6 Orders synchroniseren Als alle orders in de webwinkel worden gesynchroniseerd naar MailPlus ecom, dan kan een marketeer op basis van deze gegevens segmenteren in MailPlus ecom. Zo kan men bijvoorbeeld een gerichte e-mailing sturen naar alle mensen die in een bepaalde periode een bepaald product hebben gekocht. 6.1 Ordereigenschappen De volgende eigenschappen van een order kunnen worden ingeschoten in MailPlus ecom. OrderId (unieke referentie uit de webwinkel) Orderdatum (moment dat de order wordt geplaatst) Unieke id van de contactpersoon Product(en) van de order (alleen producten die gesynchroniseerd zijn) Totale orderbedrag (in centen) 6.2 Order toevoegen aan MailPlus ecom Als er een nieuwe order ontstaat in de webwinkel, dan dient deze direct of indirect te worden ingeschoten in MailPlus ecom via de REST API. 6.3 Order wijzigen in MailPlus ecom Als een order wordt gewijzigd in de webwinkel, dan dient deze wijziging direct of indirect ook in MailPlus ecom te worden doorgevoerd. 6.4 Order verwijderen uit MailPlus ecom Als een order wordt verwijderd (geannuleerd) in de webwinkel, dan dient deze direct of indirect ook uit MailPlus ecom te worden verwijderd. 17
7 Conversie doorgeven MailPlus ecom heeft uitgebreide mailingrapportages. Daarin kan onder andere worden getoond wat de directe conversie is geweest in de webwinkel naar aanleiding van de verzonden e-mailing. Daarnaast zijn er trendrapportages te zien, zodat de marketeer over een langere periode kan zien of de effectiviteit van zijn e-mailings toeneemt of afneemt. Er zijn twee soorten conversies die door de webwinkel naar MailPlus ecom kan worden doorgegeven: 1. De ontvanger van de e-mail maakt een nieuwe winkelwagen aan. 2. De ontvanger van de e-mail rondt een bestelling af. 18
7.1 Conversie winkelwagen aangemaakt doorgeven Op het moment dat een contactpersoon die vanuit een nieuwsbrief heeft geklikt een eerste product toevoegt aan de winkelwagen in de webwinkel, dient er door de webwinkel een signaal gegeven te worden aan MailPlus ecom. Voor de rapportages in MailPlus ecom is het van belang om te weten wie die contactpersoon is geweest. Dit is opgelost door met iedere link vanuit de e-mail naar de webwinkel een parameter mee te sturen met een bepaalde code (MailPlusId). Deze code dient te worden opgevangen door de webwinkel zodra de ontvanger van de e-mail in de webwinkel is aanbeland. De code dient door de webwinkel in de sessie bewaard te worden, zodat op het moment dat de conversie plaatsvindt deze code samen met de datum/tijd meegestuurd kan worden naar MailPlus ecom. 7.2 Conversie bestelling geplaatst doorgeven Op het moment dat een contactpersoon die vanuit een nieuwsbrief heeft geklikt een het bestelproces inclusief betalen volledig heeft doorlopen in de webwinkel, dient er door de webwinkel een signaal gegeven te worden aan MailPlus ecom. 19
Voor de rapportages in MailPlus ecom is het niet alleen van belang om te weten wie die contactpersoon is geweest, maar ook wat het totale orderbedrag is geweest en welke producten ermee gemoeid waren. Deze gegevens dienen naast de datum/tijd en de code uit MailPlus ecom, meegestuurd te worden met het conversie-signaal naar MailPlus ecom. 20
8 Automatische campagnes MailPlus ecom kent een aantal klant-en-klare automatische campagnes waarvan een deel door de webwinkel aangeroepen kunnen worden. Het gaat om campagnes die door het gedrag van de klant in de webwinkel automatisch worden aangestuurd. De volgende campagnes worden standaard geleverd bij een MailPlus ecom account: 1. Welkomscampagne bij nieuwe nieuwsbriefaanmelding 2. Verlaten winkelwagencampagne 3. Product reviewcampagne 4. Verjaardagscampagne 5. Win Back campagne De eerste 3 campagnes worden direct door de webwinkel getriggerd voor een bepaalde contactpersoon. Alleen de webwinkel weet het moment waarop dat gebeurt. De verjaardagscampagne wordt vanuit MailPlus ecom getriggerd op basis van de geboortedatum die met de contactgegevens worden gesynchroniseerd. De win back campagne wordt ook vanuit MailPlus ecom getriggerd op basis van de laatste aankoopdatum die met de contactgegevens worden gesynchroniseerd. 21
8.1 Welkomstcampagne bij aanmelding nieuwsbrief Op het moment dat een contactpersoon zich aanmeldt voor de nieuwsbrief in de webwinkel, dient het contact niet alleen toegevoegd te worden aan MailPlus ecom, maar direct erna kan er voor dat contact een automatische welkomstcampagne getriggerd worden. Vanuit de campagne wordt er dan een welkomstbericht gestuurd naar de nieuwe aanmelder. Houd er rekening mee dat aanmelden voor de nieuwsbrief in een webwinkel vaak op diverse plekken kan gebeuren: een apart formulier of een checkbox bij het het bestelproces, etc. 8.2 Verlaten winkelwagen campagne Als in de webwinkel kan worden geregistreerd dat iemand een winkelwagen heeft aangemaakt, zonder uiteindelijk te hebben afgerekend, dan is het mogelijk om op dat moment voor dat contact een verlaten winkelwagen campagne te triggeren. Er zijn talloze redenen waarom iemand een winkelwagen achterlaat zonder af te rekenen. Soms gaat het om een technische storing, bijvoorbeeld in het betaalproces. Soms gaat het om een probleem met de internetverbinding. Soms gaat het om iemand die gewoon zijn browser heeft afgesloten. Bij het triggeren van een campagne kunnen door de webwinkel gegevens worden meegestuurd die automatisch geplaatst kunnen worden in het e-mailbericht wat uiteindelijk wordt verstuurd. Denk daarbij aan producten, links, vouchers, et cetera. Deze gegevens worden campaignfields genoemd en hebben een naam, één of meerdere waardes en soms een type. Zo is het bij de verlaten winkelwagencampagne nuttig om in het e-mailbericht de producten te tonen die in de winkelwagen zaten op het moment dat die werd achtergelaten. Ook is het mogelijk om een link mee te sturen naar de verlaten winkelwagen, zodat een ontvanger van de e-mail alsnog zijn winkelwagen kan afrekenen zonder hem opnieuw te hoeven samenstellen. 22
Productgegevens tonen in een campagnebericht Omdat alle productgegevens al real-time synchroon gehouden worden met MailPlus ecom, hoeven de productgegevens niet opnieuw meegestuurd te worden bij het triggeren van de campagne. De unieke productid s zijn voldoende. Het template in MailPlus ecom bepaalt welke productgegevens getoond worden in het campagnebericht. Om de campagne zonder extra handelingen meteen te laten werken in MailPlus ecom, is het nodig om de juiste naamgeving te hanteren bij naam en type: naam = productlist type = PRODUCTLIST (in hoofdletters) Link naar winkelwagen tonen in campagnebericht Ook de link naar de verlaten winkelwagen kan automatisch geplaatst worden in het campagnebericht. Om de campagne zonder extra handelingen meteen te laten werken in MailPlus ecom, is het nodig om de juiste naamgeving te hanteren bij naam: naam = linktocart 8.3 Product review campagne Een product review campagne houdt in, dat iemand na enige tijd na de bestelling automatisch een e-mail krijgt waarin hem of haar wordt gevraagd om een review te geven op het bestelde product(en). Ook deze campagne wordt aangestuurd vanuit de webwinkel. Dat is niet op het moment dat iemand een order heeft geplaatst, maar op het moment dat de order in het backend van de webwinkel op status verzenden wordt gezet door de webwinkelier. Je wilt namelijk voorkomen dat iemand een product review e-mail krijgt, terwijl het product nooit is verzonden. Productgegevens tonen in campagnebericht Ook in het campagnebericht van de product review campagne kunnen automatisch de producten geplaatst worden die onderdeel waren van de order. Lees bij de verlaten winkelcampagne hoe je producten kunt plaatsen in een campagnebericht. 23
9 Referentie REST API methodes 9.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>voornaam.achternaam@mailplus.nl</email> <firstname>voornaam</firstname> </properties> </contact> <purge>false</purge> <update>false</update> </contactrequest> 24