Mammoet Mail XML API documentatie handleiding

De XML-taal heeft als algemeen doel Java-gebaseerde applicaties met bijvoorbeeld het in PHP geprogrammeerde Mammoet Mail 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 Mammoet Mail XML API maakt het mogelijk om contactgegevens vanuit uw eigen database te koppelen met de mailinglijsten in Mammoet Mail. U kunt hierbij gegevens toevoegen en verwijderen, zonder daarvoor in te loggen in Mammoet Mail.
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. Contactpersoon wijzigen* ^(nieuw!)
6. Foutbericht
7. Token Check
8. Contactpersonen verwijderen
9. Extra Veld Data ophalen
10. Mailinglijsten ophalen
11. Contactpersonen ophalen ^(updated!)
12. Bestaat contactpersoon?
13. E-mailadres wijzigen ^(nieuw!)
14. Nieuwsbrief statistieken ophalen ^(nieuw!)
15. Nieuwsbrief aanmaken ^(nieuw!)
16. Mailinglijst aanmaken ^(nieuw!)
17. Contactpersonen toevoegen aan geweigerde e-mail lijst ^(nieuw!)
18. Verzonden nieuwsbrief archief ophalen ^(nieuw!)

*Beschikbaar vanaf Mammoet Mail versie 6.1.3. Neem contact op voor een upgrade.

Vereisten

Om gebruik te kunnen maken van de Mammoet Mail 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/MammoetMail/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 Mammoet Mail 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 Mammoet Mail. (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@MammoetMail.com’ 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’.

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.

Contactpersoon wijzigen

De XML-document structuur voor het veld ‘Het wijzigen 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 Mammoet Mail. (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)
    • 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 wijzigen van een geldig contactpersoon 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 wijziging.
  • data – Het ID nummer van de contactpersoon.

Voorbeeld Verzoek (XML)

De volgende voorbeeldcode laat een toevoeging van de contactpersoon ‘email@mammoetmail.com’ zien aan de mailinglijst met het ID ‘1’ en met een extra veld ingesteld op ‘Jasper Reijn’ en ‘Amsterdam’.

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.

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 Mammoet Mail. (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.

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.

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 Mammoet Mail. (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.

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.

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 Mammoet Mail. (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.

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.

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 Mammoet Mail. (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.

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.

Mailinglijsten ophalen

Dit voorbeeld zal een overzicht van alle in Mammoet Mail 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 Mammoet Mail. (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 Mammoet Mail 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 Mammoet Mail aangemaakte mailinglijsten terug te geven.

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.

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 Mammoet Mail. (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)
      • Confirmed – De bevestigingsstatus van de contactpersoon die u probeert te vinden (0 of 1)
      • Format – Het format van de nieuwsbrieven waar deze contactpersoon de voorkeur aan geeft om zijn of haar nieuwsbrieven in te ontvangen (h of t)
      • Status – De status van de contactpersoon; a (active), b (bounced) of u (unsubscribed)
      • DateSearch – Filter op een specifieke datum interval gebaseerd op de inschrijfdatum. Vul de datum in als unix timestamp in het StartDate en optioneel in het EndDate veld.
        5 verschillende types:
        • after – Alle contactpersonen ingeschreven ná de opgegeven datum.
        • between – Alle contactpersonen ingeschreven tussen 2 bepaalde datums. Geef de eind datum op in het veld EndDate.
        • before – Alle contactpersonen ingeschreven vóór de opgegeven datum.
        • exact/exactly – Alle contactpersonen ingeschreven precies op de opgegeven datum.
        • not – Alle contactpersonen ingeschreven die niet zijn ingeschreven op de opgegeven datum.
      • Newsletter – Het ID van een nieuwsbrief die de contactpersoon moet hebben geopend.

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’.
Er wordt tevens gefilterd op of de contactpersoon de inschrijving heeft bevestigd of de status ‘actief’ is (en niet gebounced of uitgeschreven) of het nieuwsbrief format wat deze contactpersoon wil ontvangen HTML is, of de contactpersoon is ingeschreven ná 1 januari 2014 (unix timestamp) en of de contactpersoon de eerder verzonden nieuwsbrief met ID 2 heeft geopend.

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.

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 Mammoet Mail. (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 de 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 de 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) 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.

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.

E-mailadres wijzigen

Dit voorbeeld laat zien hoe een e-mailadres gewijzigd kan worden.

• xmlrequest (Verplicht)
  • username – De gebruikersnaam welke wordt gebruikt om in te loggen in Mammoet Mail. (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)
    • subscriberids – Het ID van de contactpersoon waarvan het e-mailadres moet worden gewijzigd. Dit ID kun je ophalen met de requestmethode “IsSubscriberOnList”. (Verplicht)
    • emailaddress – Het nieuwe e-mailadres van de contactpersoon (Verplicht)

Succesvolle Respons

Na het indienen van een geldig ‘e-mail adres wijzigen’ verzoek zal de XML API ’true’ teruggeven indien het e-mailadres van de contactpersoon is gewijzigd.

De indeling is als volgt:

• response
  • status – De waarde van het status-veld wordt als “SUCCESS” teruggeven bij een succesvolle respons.
  • data – Indien de 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) zal de het niet lukken om het e-mailadres van een contactpersoon te wijzigen. 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 wijzigt het e-mailadres van een contactpersoon.

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.

• • username – De gebruikersnaam wordt gebruikt om in te loggen op de Mammoet Mail. (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@mammoetmail.com’ 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’.

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.

Nieuwsbrief statistieken ophalen

Dit voorbeeld laat zien hoe je de statistieken van een specifieke nieuwsbrief kunt ophalen.

• xmlrequest (Verplicht)
  • username – De gebruikersnaam welke wordt gebruikt om in te loggen in Mammoet Mail. (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)
    • statid – Het ID van de statistieken die je wilt ophalen (Verplicht)
    • statstype – Het type statistieken (Verplicht)

Succesvolle Respons

Na het indienen van een geldig ‘nieuwsbrief statistieken ophalen’ verzoek zal de XML API het statistieken object teruggeven indien de statistieken worden gevonden. Hierin staan onder andere de verzendtijd, het verzendtijdstip, aantal gebouncede mail, aantal geopende mail

De indeling is als volgt:

• response
  • status – De waarde van het status-veld wordt als “SUCCESS” teruggeven bij een succesvolle respons.
  • data – Indien de statistieken worden gevonden wordt het object teruggegeven.

Afgewezen Respons

Wanneer er een foutief verzoek wordt gedaan (bijvoorbeeld als gevolg van een ontbrekend veld of een ongeldige waarde) zal de het niet lukken om de statistieken op te halen. 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 haalt het statistieken object op van een verzonden nieuwsbrief.

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.

Nieuwsbrief aanmaken

Dit voorbeeld laat zien hoe je een HTML en/of Tekst nieuwsbrief kunt aanmaken door middel van de API.

• xmlrequest (Verplicht)
  • username – De gebruikersnaam welke wordt gebruikt om in te loggen in Mammoet Mail. (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)
    • name – De naam van de nieuwsbrief (Verplicht)
    • format – Het format. Dit kan zijn, h (van HTML), t (van Tekst/plain text) of b (van Beide). Het beste is b, maar dan dien je wel zowel een tekst als HTML versie in te schieten. (Verplicht)
    • subject – Het onderwerp van de nieuwsbrief. Niet meer dan 50 karakters.
    • textbody – De content van de nieuwsbrief in plain text format.
    • htmlbody – De content van de nieuwsbrief in HTML format. Vergeet niet de CDATA-tag toe te voegen
    • createdate – Vul de datum in als unix timestamp.
    • active – Gebruik de waarde 1 om de nieuwsbrief als actief in te schieten. 0 is inactief.
    • archive – Gebruik de waarde 1 om de nieuwsbrief aan het nieuwsbrief archief toe te voegen.
    • ownerid – Zet hier de ID van de user in voor wie de nieuwsbrief zichtbaar moet zijn in Mammoet Mail.

Succesvolle Respons

Na het indienen van een geldig ‘nieuwsbrief aanmaken’ verzoek zal de XML API de ID van de nieuwsbrief teruggeven.

De indeling is als volgt:

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

Afgewezen Respons

Wanneer er een foutief verzoek wordt gedaan (bijvoorbeeld als gevolg van een ontbrekend veld of een ongeldige waarde) zal de het niet lukken om de nieuwsbrief in te schieten. 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 maakt een nieuwsbrief aan in de Mammoet Mail software.

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.

Mailinglijst aanmaken

Dit voorbeeld laat zien hoe je een HTML en/of Tekst nieuwsbrief kunt aanmaken door middel van de API.

• xmlrequest (Verplicht)
  • username – De gebruikersnaam welke wordt gebruikt om in te loggen in Mammoet Mail. (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)
    • name – De naam van de mailinglijst
    • owneremail – Het e-mailadres van de eigenaar van de lijst. Dit e-mailadres wordt ook standaard ingesteld als het afzenderadres bij het verzenden van een nieuwsbrief.
    • ownername – De naam van de eigenaar van de lijst. Deze naam wordt ook standaard ingesteld als de afzendernaam bij het verzenden van een nieuwsbrief.
    • bounceemail – Het e-mail adres waarnaar gebouncede mail moet worden verzonden zodat Mammoet Mail dit e-mailaccount kan uitlezen om gebouncede mails te verwerken.
    • replytoemail – Het e-mailadres waarop mail moet binnenkomen als ontvangers op een verzonden nieuwsbrief willen antwoorden.
    • format – Dit veld kan standaard op ‘b’ worden gezet.
    • createdate – Vul de datum in als unix timestamp.
    • notifyowner – Zet op 1 indien er een notificatie moet worden verstuurd naar het ‘owneremail’-adres wanneer er een nieuwsbrief naar deze mailinglijst wordt verzonden.
    • imapaccount – Indien het bounce-account een IMAP account is dient hier een 1 te staan. In andere gevallen (POP3) dient hier een 0 te staan.
    • bounceserver – De bounce server is het IP-adres van de server waarop het bounce-account is aangemaakt. Het is ook mogelijk bijvoorbeeld mail.domein.nl hier in te vullen.
    • bounceusername – Dit is de gebruikersnaam van het bounce-acccount.
    • bouncepassword – Dit is het wachtwoord van het bounce-account.
    • extramailsettings – Hier kunnen extra email instellingen worden ingevuld zoals; /notls, /novalidate-cert of /nossl respectievelijk; maak geen gebruik van TLS, bevestig het certificaat niet en maak geen gebruik van SSL.
    • companyname – Hier kan de bedrijfsnaam worden ingevuld zodat deze als variabele in nieuwsbrieven van worden gebruikt.
    • companyaddress – Hier kan het adres van het bedrijf worden ingevuld zodat deze als variabele in nieuwsbrieven van worden gebruikt.
    • companyphone – Hier kan het telefoonnummer van het bedrijf worden ingevuld zodat deze als variabele in nieuwsbrieven van worden gebruikt.
    • ownerid – Zet hier de ID van de user in voor wie de nieuwsbrief zichtbaar moet zijn in Mammoet Mail.
    • subscribecount – Dit is standaad 0, want er staan nog geen contactpersonen op deze lijst.
    • unsubscribecount – Dit is standaad 0, want er staan nog geen contactpersonen op deze lijst.
    • processbounce – Indien gebouncede mail verwerkt moet worden dient de waarde 1 te worden ingevuld.
    • agreedelete – Stel in op 1 als de boounce-box na het verwerken van de gebouncede mail geleegd moet worden.
    • agreedeleteall – Stel in op 1 als de boounce-box na het verwerken van de gebouncede mail geleegd moet worden.
    • visiblefields – Hier kunnen de veldkolommen worden weergegeven die in het contactpersonen overzicht zichtbaar moeten zijn. Bij het inschieten van een nieuwe lijst is dit standaard; emailaddress,subscribedate,format,status,confirmed

Succesvolle Respons

Na het indienen van een geldig ‘mailinglijst aanmaken’ verzoek zal de XML API de ID van de mailinglijst teruggeven.

De indeling is als volgt:

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

Afgewezen Respons

Wanneer er een foutief verzoek wordt gedaan (bijvoorbeeld als gevolg van een ontbrekend veld of een ongeldige waarde) zal de het niet lukken om de mailinglijst aan te maken. 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 maakt een mailinglijst aan in de Mammoet Mail software.

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.

Contactpersonen toevoegen aan geweigerde e-mail lijst

Dit voorbeeld laat zien hoe je een contactpersoon kan toevoegen aan de ‘geweigerde e-maillijst’ ofwel de supressielijst. Op de supressielijst staan contactpersonen die nooit mailings mogen ontvangen ongeacht de status van deze contactpersonen in de mailinglijsten.

• xmlrequest (Verplicht)
  • username – De gebruikersnaam welke wordt gebruikt om in te loggen in Mammoet Mail. (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)
    • emailaddress – Het e-mailadres van de contactpersoon die u wilt toevoegen aan de geweigerde email-lijst/surpressielijst (Verplicht)
    • listid – Het ID van de mailinglijst. Indien u deze niet opgeeft zal het voor alle mailinglijsten gelden.

Succesvolle Respons

Na het indienen van een geldig ‘contactpersonen toevoegen aan geweigerde e-mail lijst’ verzoek zal de XML API het onderstaande response teruggeven.

De indeling is als volgt:

• response
  • status – De waarde van het status-veld wordt als “SUCCESS” teruggeven bij een succesvolle respons.

Afgewezen Respons

Wanneer er een foutief verzoek wordt gedaan (bijvoorbeeld als gevolg van een ontbrekend veld of een ongeldige waarde) zal het niet lukken om de contactpersoon toe te voegen aan de supressielijst. 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 voegt een contactpersoon toe aan de geweigerde e-maillijst/supressielijst.

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.

Verzonden nieuwsbrief archief ophalen

Dit voorbeeld laat zien hoe je het verzonden nieuwsbrief archief kunt ophalen om deze bijvoorbeeld op uw website te publiceren.

• xmlrequest (Verplicht)
  • username – De gebruikersnaam welke wordt gebruikt om in te loggen in Mammoet Mail. (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)
    • listid – Het ID van de mailinglijst waarvan u het nieuwsbrieven archief wilt ophalen. (Verplicht)
    • num_to_retrieve – Het aantal verzonden nieuwsbrieven die u wenst op te halen.

Succesvolle Respons

Na het indienen van een geldig ‘verzonden nieuwsbrief archief ophalen’ verzoek zal de XML API het onderstaande response teruggeven.

De indeling is als volgt:

• response
  • status – De waarde van het status-veld wordt als “SUCCESS” teruggeven bij een succesvolle respons.
  • data
    • item
      • newsletterid – De ID van de mailinglijst.
      • name – De naam van de verzonden nieuwsbrief.
      • subject – Het onderwerp van de verzonden nieuwsbrief.
      • starttime – De start tijd van de verzending in UNIX tijd format.
      • listid – De ID van de mailinglijst.
      • username – De gebruikersnaam van de eigenaar van de mailinglijst waarnaar de nieuwsbrief verstuurd is.
      • fullname – De volledige naam van de eigenaar van de mailinglijst waarnaar de nieuwsbrief verstuurd is.
      • textbody – De platte tekst inhoud van de verzonden nieuwsbrief.
      • htmlbody – De HTML inhoud van de verzonden nieuwsbrief.

Afgewezen Respons

Wanneer er een foutief verzoek wordt gedaan (bijvoorbeeld als gevolg van een ontbrekend veld of een ongeldige waarde) zal het niet lukken om het archief van de nieuwsbrief op te halen. 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 voegt een contactpersoon toe aan de geweigerde e-maillijst/supressielijst.

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.