MailCamp XML API documentatie handleiding

De XML-taal heeft als algemeen doel Java-gebaseerde applicaties met bijvoorbeeld het in PHP geprogrammeerde MailCamp te kunnen laten communiceren.

Een application programming interface (API) is een verzameling definities op basis waarvan een computerprogramma of script kan communiceren met een ander programma of script.

Een API definieert de toegang tot de functionaliteit die er achter schuil gaat. De buitenwereld kent geen details van de functionaliteit of implementatie, maar weet dankzij de API wel hoe deze kan worden aangesproken. Een voordeel hiervan is dat met een API meerdere implementaties benaderbaar kunnen zijn, zolang deze maar voldoen aan de API.

Dit document is een handleiding voor het implementeren van de API koppeling.

De MailCamp XML API maakt het mogelijk om contactgegevens vanuit uw eigen database te koppelen met de mailinglijsten in MailCamp. U kunt hierbij gegevens toevoegen en verwijderen, zonder daarvoor in te loggen in MailCamp.
Voorbeeld: U laat inschrijvers op uw nieuwbrief in uw eigen database binnenkomen en verstuurt deze gegevens op het moment dat u dat wilt. Zo blijft uw eigen database leidend.

  1. Vereisten
  2. Het indien van een verzoek
  3. Mogelijke verzoeken
  4. Contactpersoon toevoegen aan een mailinglijst
  5. Foutbericht
  6. Token Check
  7. Contactpersonen verwijderen
  8. Extra Veld Data ophalen
  9. Mailinglijsten ophalen
  10. Contactpersonen ophalen
  11. Bestaat contactpersoon?

Vereisten

Om gebruik te kunnen maken van de MailCamp XML API is een server met PHP 5.1.2 of hoger vereist.

Het indienen van een verzoek

Om een verzoek in te kunnen dienen, moet een XML POST-verzoek worden verstuurd naar het 'XML Pad'. Deze kunt u vinden in de 'Gebruikersaccount -> Wijzig gebruiker' sectie onder de tab 'Gebruikers Permissies'. Zorg ervoor dat 'Inschakelen van de XML API' is aangevinkt en opgeslagen. Het XML-pad ziet er ongeveer als volgt uit:

http://www.uwdomein.com/mailcamp/xml.php

De 'Gebruikersnaam' en 'usertoken' genoemd in de volgende voorbeelden zijn te vinden in dezelfde sectie respectievelijk onder de titel 'XML Gebruikersnaam' en 'XML token'.

Mogelijke verzoeken

Deze sectie beschrijft de verschillende functies die kunnen worden gebruikt door de MailCamp XML-API.

Contactpersoon toevoegen aan een mailinglijst

De XML-document structuur voor het veld 'Het toevoegen van een abonnee en verzoek bijbehorende informatie op maat' is als volgt:

  • xmlrequest (Verplicht)
    • username – De gebruikersnaam wordt gebruikt om in te loggen op de MailCamp. (Verplicht)
    • usertoken – De unieke token toegewezen aan de hierboven genoemde gebruiker. (Verplicht)
    • requesttype – De naam van het betreffende API-bestand. (Verplicht)
    • requestmethod – De naam van de functie die wordt opgeroepen. (Verplicht)
    • details (Verplicht)
      • emailaddress – Het e-mailadres van de contactpersoon die wordt toegevoegd. (Verplicht)
      • mailinglistid – De mailinglijst waarin de contactpersoon staat. (Verplicht)
      • confirmed – Zet de bevestigingsstatus van de contactpersoon op bevestigd of niet (yes of y of true of 1) (Niet verplicht, standaard onbevestigd)
      • format – Het format van de nieuwsbrieven waar deze contactpersoon de voorkeur aan geeft om zijn of haar nieuwsbrieven in te ontvangen (html of h of text of t) (standaard text)
      • customfields
        • item
          • fieldid – Het id van het extra veld dat dient te worden toegevoegd.
          • value – De waarde die aan het extra veld moet worden toegekend.

Succesvolle Respons

Na het toevoegen van een geldig contactpersoon aan een mailinglijst wordt het ID van deze contactpersoon 'teruggegeven'.

De indeling is als volgt:

  • response
    • status – De waarde van het status-veld wordt als “SUCCESS” teruggeven bij een succesvolle toevoeging.
    • data – Het ID nummer van de contactpersoon.

Voorbeeld Verzoek (XML)

De volgende voorbeeldcode laat een toevoeging van de contactpersoon ‘email@mailcamp.nl’ zien aan de mailinglijst met het ID ‘1’, status ingesteld op ‘bevestigd’, format ingesteld op ‘html’ en met een extra veld ingesteld op ‘Jasper Reijn’.

  1. <xmlrequest>   
  2.     <username>admin</username>   
  3.     <usertoken>d467e49b221137215ebdab1ea4e046746de7d0ea</usertoken>   
  4.     <requesttype>subscribers</requesttype>   
  5.     <requestmethod>AddSubscriberToList</requestmethod>   
  6.     <details>   
  7.         <emailaddress>email@mailcamp.nl</emailaddress>   
  8.         <mailinglist>1</mailinglist>   
  9.         <format>html</format>   
  10.         <confirmed>yes</confirmed>   
  11.         <customfields>   
  12.             <item>   
  13.                 <fieldid>1</fieldid>   
  14.                 <value>Jasper Reijn</value>   
  15.             </item>   
  16.         </customfields>   
  17.     </details>   
  18. </xmlrequest>  

Voorbeeld Verzoek (PHP)

De volgende voorbeeldcode is geschreven in PHP en maakt gebruik van CURL PHP's functionaliteit om de bovenstaande XML toe te voegen in de applicatie.

  1. <?php   
  2. $xml = '<xmlrequest>   
  3.     <username>admin</username>   
  4.     <usertoken>d467e49b221137215ebdab1ea4e046746de7d0ea</usertoken>   
  5.     <requesttype>subscribers</requesttype>   
  6.     <requestmethod>AddSubscriberToList</requestmethod>   
  7.     <details>   
  8.         <emailaddress>email@mailcamp.nl</emailaddress>   
  9.         <mailinglist>1</mailinglist>   
  10.         <format>html</format>   
  11.         <confirmed>yes</confirmed>   
  12.         <customfields>   
  13.             <item>   
  14.                 <fieldid>1</fieldid>   
  15.                 <value>Jasper Reijn</value>   
  16.             </item>   
  17.         </customfields>   
  18.     </details>   
  19. </xmlrequest>   
  20. ';   
  21.   
  22. $ch = curl_init('http://www.uwdomein.nl/mailcamp/xml.php');   
  23. curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);   
  24. curl_setopt($ch, CURLOPT_POST, 1);   
  25. curl_setopt($ch, CURLOPT_POSTFIELDS, $xml);   
  26. $result = @curl_exec($ch);   
  27. if($result === false) {   
  28.     echo "Error performing request";   
  29. }   
  30. else {   
  31.     $xml_doc = simplexml_load_string($result);   
  32.     echo 'Status is ', $xml_doc->status, '<br/>';   
  33.     if ($xml_doc->status == 'SUCCESS') {   
  34.         echo 'Data is ', $xml_doc->data, '<br/>';   
  35.     } else {   
  36.         echo 'Error is ', $xml_doc->errormessage, '<br/>';   
  37.     }   
  38. }   
  39.   
  40. ?>  

Foutbericht

Dit voorbeeld demonstreert een foutbericht dat wordt geretourneerd wanneer een incorrect verzoek wordt ingediend.

Let op! Wanneer de tag in het voorbeeld niet gesloten is, wordt er geen ListId gestuurd.

De XML-document structuur voor dit voorbeeld is als volgt:

  • xmlrequest (Verplicht)
    • username – De gebruikersnaam die gebruikt wordt om in te loggen in MailCamp. (Verplicht)
    • usertoken – De unieke token toegewezen aan de hierboven genoemde gebruiker. (Verplicht)
    • requesttype – De naam van het betreffende API-bestand. (Verplicht)
    • requestmethod – De naam van de functie die wordt aangeroepen. (Verplicht)
    • details (Verplicht)

Afgewezen Respons

Bij het indienen van een incorrect verzoek, als gevolg van een ontbrekend veld of een ongeldige waarde, zal het verzoek mislukken. Een statusbericht met uitleg zal worden teruggegeven via XML.

In dit voorbeeld zal de volgende foutmelding worden weergegeven:

'De XML die u heeft opgegeven is niet geldig. 'Controleer uw XML-document en probeer het opnieuw.'

De indeling is als volgt:

  • response
    • status – De waarde van het status-veld zal “ERROR” zijn.
    • errormessage – Een boodschap om uit te leggen waarom het verzoek is mislukt.

Voorbeeld Verzoek (XML)

De volgende voorbeeldcode zal proberen de mailinglijsten op te halen.

  1. <xmlrequest>   
  2.     <username>admin</username>   
  3.     <usertoken>78701d1ba2588ea1991f44299b814129658c6947</usertoken>   
  4.     <requesttype>lists</requesttype>   
  5.     <requestmethod>GetLists</requestmethod>   
  6.     <details>
  7.         <lists/>
  8.         <sortinfo/>
  9.         <countonly/>
  10.         <start/>
  11.         <perpage/>
  12.     </details> 
  13. </xmlrequest> 

Voorbeeld Verzoek (PHP)

De volgende voorbeeldcode is geschreven in PHP en maakt gebruik van CURL PHP's functionaliteit om de bovenstaande XML toe te voegen in de applicatie.

  1. <?php   
  2. $xml = '<xmlrequest>   
  3.     <username>admin</username>   
  4.     <usertoken>78701d1ba2588ea1991f44299b814129658c6947</usertoken>   
  5.     <requesttype>lists</requesttype>   
  6.     <requestmethod>GetLists</requestmethod>
  7.     <details>
  8.         <lists/>
  9.         <sortinfo/>
  10.         <countonly/>
  11.         <start/>
  12.         <perpage/>
  13.     </details> 
  14. </xmlrequest>';   
  15.   
  16. $ch = curl_init('http://www.uwdomein.nl/mailcamp/xml.php');   
  17. curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);   
  18. curl_setopt($ch, CURLOPT_POST, 1);   
  19. curl_setopt($ch, CURLOPT_POSTFIELDS, $xml);   
  20. $result = @curl_exec($ch);   
  21. if($result === false) {   
  22.     echo "Error performing request";   
  23. }   
  24. else {   
  25.     $xml_doc = simplexml_load_string($result);   
  26.     echo 'status is ', $xml_doc->status, '<br/>';   
  27.     if ($xml_doc->status == 'SUCCESS') {   
  28.         print_r($result);   
  29.         } else {   
  30.         echo 'Error is ', $xml_doc->errormessage, '<br/>';   
  31.     }   
  32. }?>  

Token Check

Dit voorbeeld controleert of de token die u gebruikt, geldig is.

Merk op dat de gegevens tag in het voorbeeld nog steeds is opgenomen, ook al zijn er geen gegevens nodig.

  • xmlrequest (Verplicht)
    • username – De gebruikersnaam welke wordt gebruikt om in te loggen in MailCamp. (Verplicht)
    • usertoken – De unieke token toegewezen aan de hierboven genoemde gebruiker. (Verplicht)
    • requesttype – De naam van het betreffende API-bestand. (Verplicht)
    • requestmethod – De naam van de functie die wordt aangeroepen. (Verplicht)
    • details (Verplicht)

Succesvolle Respons

Na het indienen van een geldig 'Check Token' verzoek zal de XML API 'true' teruggeven.

De indeling is als volgt:

  • response
    • status – De waarde van het status-veld wordt als “SUCCESS” teruggeven bij een succesvolle respons.
    • data – Dit zal ‘1’ zij bij een succesvolle autorisatie.

Afgewezen Respons

Na het indienen van een foutief verzoek als gevolg van een ontbrekend veld of een ongeldige waarde zal het 'Check Token' verzoek mislukken. Een statusbericht met uitleg zal worden teruggegeven via XML.

In dit voorbeeld zal de volgende foutmelding worden weergegeven:

‘Ongeldige gegevens’

De indeling is als volgt:

  • response
    • status – De waarde van het status-veld zal “ERROR” zijn.
    • errormessage – Een tekstuele boodschap om uit te leggen waarom het verzoek is mislukt.

Voorbeeld Verzoek (XML)

De volgende voorbeeldcode voert een control uit op de usertoken om te kijken of deze geldig is.

  1. <xmlrequest>
  2.     <username>admin</username>
  3.     <usertoken>78701d1ba2588ea1991f44299b814129658c6947</usertoken>
  4.     <requesttype>authentication</requesttype>
  5.     <requestmethod>xmlapitest</requestmethod>
  6.     <details>
  7.     </details>
  8. </xmlrequest> 

Voorbeeld Verzoek (PHP)

De volgende voorbeeldcode is geschreven in PHP en maakt gebruik van CURL PHP's functionaliteit om de bovenstaande XML toe te voegen in de applicatie.

  1. <?php   
  2. $xml = '<xmlrequest>   
  3.     <username>admin</username>   
  4.     <usertoken>78701d1ba2588ea1991f44299b814129658c6947</usertoken>   
  5.     <requesttype>authentication</requesttype>   
  6.     <requestmethod>xmlapitest</requestmethod>   
  7.     <details>   
  8.     </details>   
  9. </xmlrequest>';   
  10.   
  11. $ch = curl_init('http://www.uwdomein.nl/mailcamp/xml.php');   
  12. curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);   
  13. curl_setopt($ch, CURLOPT_POST, 1);   
  14. curl_setopt($ch, CURLOPT_POSTFIELDS, $xml);   
  15. $result = @curl_exec($ch);   
  16. if($result === false) {   
  17.     echo "Error performing request";   
  18. }   
  19. else {   
  20.     $xml_doc = simplexml_load_string($result);   
  21.     echo 'status is ', $xml_doc->status, '<br/>';   
  22.     if ($xml_doc->status == 'SUCCESS') {   
  23.         print_r($result);   
  24.         } else {   
  25.         echo 'Error is ', $xml_doc->errormessage, '<br/>';   
  26.     }   
  27. }   
  28. ?>  

Contactpersonen verwijderen

Dit voorbeeld laat zien hoe u een contactpersoon verwijderd uit een mailinglijst.

  • xmlrequest (Verplicht)
    • username – De gebruikersnaam welke wordt gebruikt om in te loggen in MailCamp. (Verplicht)
    • usertoken – De unieke token toegewezen aan de hierboven genoemde gebruiker. (Verplicht)
    • requesttype – De naam van het betreffende API-bestand. (Verplicht)
    • requestmethod – De naam van de functie die wordt aangeroepen. (Verplicht)
    • details (Verplicht)
      • list – Het ID van de mailinglijst waarin u wenst te zoeken (Verplicht)
      • emailaddress – Het e-mailadres van de contactpersoon die u probeert te lokaliseren (Verplicht)

Succesvolle Respons

Bij het indienen van een geldig ‘contactpersoon verwijderen’ verzoek zal de XML API een succesvolle status teruggeven.

De indeling is als volgt:

  • response
    • status – De waarde van het status-veld wordt als “SUCCESS” teruggeven bij een succesvolle respons.
    • data
      • item - Het aantal contactpersonen dat correct is verwijderd.

Afgewezen Respons

Na het indienen van een foutief verzoek als gevolg van een ontbrekend veld of een ongeldige waarde zal het verzoek om een contactpersoon te verwijderen mislukken. Een statusbericht met uitleg zal worden teruggegeven via XML.

De indeling is als volgt:

  • response
    • status – De waarde van het status-veld zal “ERROR” zijn.
    • errormessage –Een tekstuele boodschap om uit te leggen waarom het verzoek is mislukt.

Voorbeeld Verzoek (XML)

De volgende voorbeeldcode zal het gegeven e-mailadres verwijderen uit de mailinglijst met de betreffende ID.

  1. <xmlrequest>   
  2.     <username>admin</username>   
  3.     <usertoken>78701d1ba2588ea1991f44299b814129658c6947</usertoken>   
  4.     <requesttype>subscribers</requesttype>   
  5.     <requestmethod>DeleteSubscriber</requestmethod>   
  6.     <details>   
  7.         <emailaddress>email@mailcamp.nl</emailaddress>   
  8.         <listid>1</listid>   
  9.         <subscriberid />  
  10.     </details>   
  11. </xmlrequest>  

Voorbeeld Verzoek (PHP)

De volgende voorbeeldcode is geschreven in PHP en maakt gebruik van CURL PHP's functionaliteit om de bovenstaande XML toe te voegen in de applicatie.

  1. <?php   
  2. $xml = '<xmlrequest>   
  3.     <username>admin</username>   
  4.     <usertoken>78701d1ba2588ea1991f44299b814129658c6947</usertoken>   
  5.     <requesttype>subscribers</requesttype>   
  6.     <requestmethod>DeleteSubscriber</requestmethod>   
  7.     <details>   
  8.         <emailaddress>email@mailcamp.nl</emailaddress>   
  9.         <list>1</list>  
  10.         <subscriberid />
  11.     </details>   
  12. </xmlrequest>';   
  13.   
  14. $ch = curl_init('http://www.uwdomein.nl/mailcamp/xml.php');   
  15. curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);   
  16. curl_setopt($ch, CURLOPT_POST, 1);   
  17. curl_setopt($ch, CURLOPT_POSTFIELDS, $xml);   
  18. $result = @curl_exec($ch);   
  19. if($result === false) {   
  20.     echo "Error performing request";   
  21. }   
  22. else {   
  23.     $xml_doc = simplexml_load_string($result);   
  24.     echo 'status is ', $xml_doc->status, '<br/>';   
  25.     if ($xml_doc->status == 'SUCCESS') {   
  26.         print_r($result);   
  27.         } else {   
  28.         echo 'Error is ', $xml_doc->errormessage, '<br/>';   
  29.     }   
  30. }   
  31. ?>  

Extra Veld Data ophalen

De XML document structuur voor het ophalen van extra velden van een mailinglijst is als volgt:

  • xmlrequest (Verplicht)
    • username – De gebruikersnaam welke wordt gebruikt om in te loggen in MailCamp. (Verplicht)
    • usertoken – De unieke token toegewezen aan de hierboven genoemde gebruiker. (Verplicht)
    • requesttype – De naam van het betreffende API-bestand. (Verplicht)
    • requestmethod – De naam van de functie die wordt aangeroepen. (Verplicht)
    • details (Verplicht)
      • listids – De ID's van de mailinglijst waarvoor de extra veld gegevens worden opgevraagd. (Verplicht)

Succesvolle Respons

Bij het indienen van een geldig ‘Extra Veld Data ophalen’ verzoek worden de extra velden gegevens door de XML API teruggegeven.

De indeling is als volgt:

  • response
    • status – De waarde van het status-veld wordt als “SUCCESS” teruggeven bij een succesvolle respons.
    • data
    • item
      • fieldid – Het ID nummer van het betreffende extra veld.
      • name – De naam van het extra veld.
      • fieldtype – Het extra veld type (tekst, getal etc.).
      • defaultvalue – Indien u een standaard waarde heeft ingevuld zal die hier worden weergegeven.
      • required – Indien het een verplicht veld is zal dit hier worden weergegeven (1 of 0).
      • fieldsettings – Seriële versie van de extra velden instellingen

Afgewezen Respons

Na het indienen van een foutief verzoek als gevolg van een ontbrekend veld of een ongeldige waarde zal het verzoek om de Extra Velden Data op te halen mislukken. Een statusbericht met uitleg zal worden teruggegeven via XML.

De indeling is als volgt:

  • response
    • status – De waarde van het status-veld zal “ERROR” zijn.
    • errormessage – Een tekstuele boodschap om uit te leggen waarom het verzoek is mislukt.

Voorbeeld Verzoek (XML)

De volgende voorbeeldcode zal alle informatie van de extra velden van de lijst met het ID '1' weergeven.

  1. <xmlrequest>   
  2.     <username>admin</username>   
  3.     <usertoken>78701d1ba2588ea1991f44299b814129658c6947</usertoken>   
  4.     <requesttype>lists</requesttype>   
  5.     <requestmethod>GetCustomFields</requestmethod>   
  6.     <details>   
  7.         <listids>   
  8.             1   
  9.         </listids>   
  10.     </details>   
  11. </xmlrequest> 

Voorbeeld Verzoek (PHP)

De volgende voorbeeldcode is geschreven in PHP en maakt gebruik van CURL PHP's functionaliteit om de bovenstaande XML toe te voegen in de applicatie.

  1. <?php   
  2. $xml = '<xmlrequest>   
  3.     <username>admin</username>   
  4.     <usertoken>78701d1ba2588ea1991f44299b814129658c6947</usertoken>   
  5.     <requesttype>lists</requesttype>   
  6.     <requestmethod>GetCustomFields</requestmethod>   
  7.     <details>   
  8.         <listids>   
  9.             1   
  10.         </listids>   
  11.     </details>   
  12. </xmlrequest>   
  13. ';   
  14.   
  15. $ch = curl_init('http://www.uwdomein.nl/mailcamp/xml.php');   
  16. curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);   
  17. curl_setopt($ch, CURLOPT_POST, 1);   
  18. curl_setopt($ch, CURLOPT_POSTFIELDS, $xml);   
  19. $result = @curl_exec($ch);   
  20. if($result === false) {   
  21.     echo "Error performing request";   
  22. }   
  23. else {   
  24.     $xml_doc = simplexml_load_string($result);   
  25.     echo 'status is ', $xml_doc->status, '<br/>';   
  26.     if ($xml_doc->status == 'SUCCESS') {   
  27.         print_r($result);   
  28.         } else {   
  29.         echo 'Error is ', $xml_doc->errormessage, '<br/>';   
  30.     }   
  31. }   
  32. ?>  

Mailinglijsten ophalen

Dit voorbeeld zal een overzicht van alle in MailCamp aangemaakte mailinglijsten weergeven in een XML met de gevonden data.

Merk op dat de details tag in het voorbeeld nog steeds is opgenomen, ook al zijn er geen gegevens nodig.
  • xmlrequest (Verplicht)
    • username – De gebruikersnaam welke wordt gebruikt om in te loggen in MailCamp. (Verplicht)
    • usertoken – De unieke token toegewezen aan de hierboven genoemde gebruiker. (Verplicht)
    • requesttype – De naam van het betreffende API-bestand. (Verplicht)
    • requestmethod – De naam van de functie die wordt aangeroepen. (Verplicht)
    • details (Verplicht)

Succesvolle Respons

Na het indienen van een geldig ‘Mailinglijsten ophalen’ verzoek zal de XML API alle gevonden data van de in MailCamp mailinglijsten teruggeven in een XML.

De indeling is als volgt:

  • response
    • status – De waarde van het status-veld wordt als “SUCCESS” teruggeven bij een succesvolle respons.
    • data
      • item
        • listid – De ID van de mailinglijst.
        • name – De naam van de mailinglijst.
        • subscribecount – Het totaal aantal ingeschreven contactpersonen.
        • unsubscribecount – Het totaal aantal uitgeschreven contactpersonen.
        • autorespondercount – Het aantal autoresponders die zijn gelinkt aan de betreffende mailinglijst.

Afgewezen Respons

Na het indienen van een foutief verzoek als gevolg van een ontbrekend veld of een ongeldige waarde zal het verzoek om mailinglijsten op te halen mislukken. Een statusbericht met uitleg zal worden teruggegeven via XML.

In dit voorbeeld zal de volgende foutmelding worden weergegeven:

‘Ongeldige gegevens’

De indeling is als volgt:

  • response
    • status – De waarde van het status-veld zal “ERROR” zijn.
    • errormessage – Een tekstuele boodschap om uit te leggen waarom het verzoek is mislukt.

Voorbeeld Verzoek (XML)

De volgende voorbeeldcode doet een verzoek om alle in MailCamp aangemaakte mailinglijsten terug te geven.

  1. <xmlrequest>   
  2.     <username>admin</username>   
  3.     <usertoken>78701d1ba2588ea1991f44299b814129658c6947</usertoken>   
  4.     <requesttype>lists</requesttype>   
  5.     <requestmethod>GetLists</requestmethod>   
  6.     <details>
  7.         <lists />
  8.         <sortinfo />
  9.         <countonly />
  10.         <start />
  11.         <perpage />
  12.     </details>   
  13. </xmlrequest>  

Voorbeeld Verzoek (PHP)

De volgende voorbeeldcode is geschreven in PHP en maakt gebruik van CURL PHP's functionaliteit om de bovenstaande XML toe te voegen in de applicatie.

  1. <?php   
  2. $xml = '<xmlrequest>   
  3.     <username>admin</username>   
  4.     <usertoken>78701d1ba2588ea1991f44299b814129658c6947</usertoken>   
  5.     <requesttype>lists</requesttype>   
  6.     <requestmethod>GetLists</requestmethod>   
  7.     <details>
  8.         <lists />
  9.         <sortinfo />
  10.         <countonly />
  11.         <start />
  12.         <perpage />
  13.     </details>   
  14. </xmlrequest>';   
  15.   
  16. $ch = curl_init('http://www.uwdomein.nl/mailcamp/xml.php');   
  17. curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);   
  18. curl_setopt($ch, CURLOPT_POST, 1);   
  19. curl_setopt($ch, CURLOPT_POSTFIELDS, $xml);   
  20. $result = @curl_exec($ch);   
  21. if($result === false) {   
  22.     echo "Error performing request";   
  23. }   
  24. else {   
  25.     $xml_doc = simplexml_load_string($result);   
  26.     echo 'status is ', $xml_doc->status, '<br/>';   
  27.     if ($xml_doc->status == 'SUCCESS') {   
  28.         print_r($result);   
  29.         } else {   
  30.         echo 'Error is ', $xml_doc->errormessage, '<br/>';   
  31.     }   
  32. }   
  33. ?>  

Contactpersonen ophalen

Dit voorbeeld geeft een XML terug met het totaal aantal contactpersonen van een bepaalde mailinglijst, alsmede een overzicht van alle contactpersonen in de betreffende lijst.

  • xmlrequest (Verplicht)
    • username – De gebruikersnaam welke wordt gebruikt om in te loggen in MailCamp. (Verplicht)
    • usertoken – De unieke token toegewezen aan de hierboven genoemde gebruiker. (Verplicht)
    • requesttype – De naam van het betreffende API-bestand. (Verplicht)
    • requestmethod – De naam van de functie die wordt aangeroepen. (Verplicht)
    • details (Verplicht)
      • searchinfo
        • List – Het ID van de mailinglijst waarin u wenst te zoeken (Verplicht)
        • Email – Het e-mailadres van de contactpersoon die u probeert te vinden (Verplicht)

Succesvolle Respons

Na het indien van een geldig ‘contactpersonen ophalen’ verzoek zal de XML API het totaal aantal contactpersonen van de betreffende mailinglijst als XML teruggeven, alsmede een overzicht van alle contactpersonen.

De indeling is als volgt:

  • response
    • status – De waarde van het status-veld wordt als “SUCCESS” teruggeven bij een succesvolle respons.
    • data
      • count – Het totale aantal contactpersonen.
      • subscriberlist – Een overzicht van alle e-mailadressen van de contactpersonen.

Afgewezen Respons

Na het indienen van een foutief verzoek als gevolg van een ontbrekend veld of een ongeldige waarde zal het verzoek om de contactpersonen op te halen mislukken. Een statusbericht met uitleg zal worden teruggegeven via XML.

De indeling is als volgt:

  • response
    • status – De waarde van het status-veld zal “ERROR” zijn.
    • errormessage – Een tekstuele boodschap om uit te leggen waarom het verzoek is mislukt.

Voorbeeld Verzoek (XML)

De volgende voorbeeldcode doet een check op de mailinglijst met het ID ‘1’ voor alle emailadressen gerelateerd aan het volgende domein: ‘@uwdomein.nl’.

  1. <xmlrequest>   
  2.     <username>admin</username>   
  3.     <usertoken>78701d1ba2588ea1991f44299b814129658c6947</usertoken>   
  4.     <requesttype>subscribers</requesttype>   
  5.     <requestmethod>GetSubscribers</requestmethod>   
  6.     <details>   
  7.         <searchinfo>   
  8.             <listids>1</listids>   
  9.             <emailaddress>@uwdomein.nl</emailaddress>   
  10.         </searchinfo>   
  11.     </details>   
  12. </xmlrequest> 

Voorbeeld Verzoek (PHP)

De volgende voorbeeldcode is geschreven in PHP en maakt gebruik van CURL PHP's functionaliteit om de bovenstaande XML toe te voegen in de applicatie.

  1. <?php   
  2. $xml = '<xmlrequest>   
  3.     <username>admin</username>   
  4.     <usertoken>78701d1ba2588ea1991f44299b814129658c6947</usertoken>   
  5.     <requesttype>subscribers</requesttype>   
  6.     <requestmethod>GetSubscribers</requestmethod>   
  7.     <details>   
  8.         <searchinfo>   
  9.             <listids>1</listids>   
  10.             <emailaddress>@uwdomein.nl</emailaddress>   
  11.         </searchinfo>   
  12.     </details>   
  13. </xmlrequest>';   
  14.   
  15. $ch = curl_init('http://www.uwdomein.nl/mailcamp/xml.php');   
  16. curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);   
  17. curl_setopt($ch, CURLOPT_POST, 1);   
  18. curl_setopt($ch, CURLOPT_POSTFIELDS, $xml);   
  19. $result = @curl_exec($ch);   
  20. if($result === false) {   
  21.     echo "Error performing request";   
  22. }   
  23. else {   
  24.     $xml_doc = simplexml_load_string($result);   
  25.     echo 'status is ', $xml_doc->status, '<br/>';   
  26.     if ($xml_doc->status == 'SUCCESS') {   
  27.         print_r($result);   
  28.         } else {   
  29.         echo 'Error is ', $xml_doc->errormessage, '<br/>';   
  30.     }   
  31. }   
  32. ?>  

Bestaat contactpersoon?

Dit voorbeeld laat zien of een e-mailadres voorkomt in een specifieke mailinglijst.

  • xmlrequest (Verplicht)
    • username – De gebruikersnaam welke wordt gebruikt om in te loggen in MailCamp. (Verplicht)
    • usertoken – De unieke token toegewezen aan de hierboven genoemde gebruiker. (Verplicht)
    • requesttype – De naam van het betreffende API-bestand. (Verplicht)
    • requestmethod – De naam van de functie die wordt aangeroepen. (Verplicht)
    • details (Verplicht)
      • Email – Het e-mailadres van de contactpersoon waar naar wordt gezocht (Verplicht)
      • List – Het ID van de mailinglijst waar op wordt gezocht (Verplicht)

Succesvolle Respons

Na het indienen van een geldig ‘komt deze contactpersoon voor op deze lijst?’ verzoek zal de XML API 'true' teruggeven indien het contactpersoon wordt gevonden. Het geeft niets terug indien de persoon niet wordt gevonden.

De indeling is als volgt:

  • response
    • status – De waarde van het status-veld wordt als “SUCCESS” teruggeven bij een succesvolle respons.
    • data – Indien het contactpersoon bestaat wordt ‘1’ teruggegeven.

Afgewezen Respons

Wanneer er een foutief verzoek wordt gedaan (bijvoorbeeld als gevolg van een ontbrekend veld of een ongeldige waarde) Dan zal de het niet lukken om een contactpersonen statuscheck te doen. Een statusbericht met uitleg zal worden teruggegeven via XML.

De indeling is als volgt:

  • response
    • status – De waarde van het status-veld zal “ERROR” zijn.
    • errormessage – Een tekstuele boodschap om uit te leggen waarom het verzoek is mislukt.

Voorbeeld Verzoek (XML)

De volgende voorbeeldcode doet een check op een mailinglijst om te zien of een specieke contactpersoon op de mailinglijst voorkomt.

  1. <xmlrequest>     
  2.       <username>admin</username>     
  3.        <usertoken>78701d1ba2588ea1991f44299b814129658c6947</usertoken>     
  4.     <requesttype>subscribers</requesttype>   
  5.         <requestmethod>IsSubscriberOnList</requestmethod>   
  6.     <details>   
  7.         <emailaddress>email@mailcamp.nl</emailaddress>   
  8.         <listids>1</listids>
  9.         <subscriberid />
  10.         <activeonly />
  11.         <not_bounced />
  12.         <return_listid />
  13.     </details>   
  14. </xmlrequest> 

Voorbeeld Verzoek (PHP)

De volgende voorbeeldcode is geschreven in PHP en maakt gebruik van CURL PHP's functionaliteit om de bovenstaande XML toe te voegen in de applicatie.

  1. <?php   
  2. $xml = ' <requesttype>subscribers</requesttype>   
  3.     <requestmethod>IsSubscriberOnList</requestmethod>   
  4.     <details>   
  5.         <emailaddress>email@mailcamp.nl</emailaddress>   
  6.         <listids>1</listids>
  7.         <subscriberid />
  8.         <activeonly />
  9.         <not_bounced />
  10.         <return_listid />
  11.     </details>   
  12. </xmlrequest>';   
  13.   
  14. $ch = curl_init('http://www.uwdomein.nl/mailcamp/xml.php');   
  15. curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);   
  16. curl_setopt($ch, CURLOPT_POST, 1);   
  17. curl_setopt($ch, CURLOPT_POSTFIELDS, $xml);   
  18. $result = @curl_exec($ch);   
  19. if($result === false) {   
  20.     echo "Error performing request";   
  21. }   
  22. else {   
  23.     $xml_doc = simplexml_load_string($result);   
  24.     echo 'status is ', $xml_doc->status, '<br/>';   
  25.     if ($xml_doc->status == 'SUCCESS') {   
  26.         print_r($result);   
  27.         } else {   
  28.         echo 'Error is ', $xml_doc->errormessage, '<br/>';   
  29.     }   
  30. }   
  31. ?>