API

De MailingLijst API is ontwikkeld voor webbouwers die de (adres)gegevens in MailingLijst willen bewerken zonder tussenkomst van pop-ups en dergelijke. Doel is om online, via een url bewerken van de gegevens in MailingLijst. Hierbij wordt geen ‘dialoog’ geopend, maar direct verwerkt en de resultaten aan de aanroepende url terugegeven in een xml-document.

Aanroepformaat
De [url]= http://www.mailinglijst.eu/api
Verplichte parameters: ?key= en &action

Retour
Een xml-bestand met een resultaatcode en een toelichting (engels).

Beveiliging
o De url heeft een KEY-parameter (GUID) die moet overeenkomen met die van de klantgegevens (member)
o De referrer (ip-nummer van de aanroepende machine) moet bekend zijn gemaakt in het MailingLijst CMS (dit kunnen meerdere ip-nummers/ranges zijn per member)
o De klant moet rechten hebben om on-line ACTIONS te kunnen uitvoeren. Dit is wordt ingesteld in het MailingLijst CMS per action.

Multi-Accounts
Bij MailingLijst abonnees die gebruik maken van de Multi-account moet de parameter &a= worden meegegeven om aan te geven welke rechten benodigd zijn voor het adres.

Testen (sandbox)
Voor het testen van de MAILINGLIJST–API is een speciale testomgeving (een zgn SANDBOX) ingericht waarin u (samen met anderen) ongebreideld kunt testen.
De sandbox staat open voor alle ip-nummers en vereist parameters: ?key=xx&a=yy

key = 79833568-fd20-4955-b915-5d89aa73510c
a=34

Inloggegevens MailingLijst:
Inlognaam: demo
Account: sandbox
Wachtwoord: s@ndb0x

De sandbox-account wordt periodiek ‘opgeschoond’.

Acties
De [url] heeft een action-parameter. Deze kan zijn:

SUBSCRIBE                aanmelden op een mailinglijst
UNSUBSCRIBE            afmelden van een mailinglijst
EDIT                          bijwerken van (adres) gegevens
GET                           opvragen adresgegevens van enkel adres
BLACKLISTADD          e-mailadres toevoegen aan de blacklist
BLACKLISTDELETE      verwijder een adres van de blacklist
LISTGET                    opvragen lijstgegevens
LISTCODEGROUP       opvragen codegroep bijv. talen.
BODYPOST                posten van de mailingbody.

Ad SUBSCRIBE (Abonneren)
Bij een abonneer- actie is minimaal het e-mailadres/adres guid én het lijstnummer benodigd.

Om een adres te abonneren op een lijst kan worden gekozen voor:
[url]?key=[key]&action=SUBSCRIBE&l=100359&e=sandbox@mailinglijst.nl

Indien het unieke adresnummer (guid) bekend is kan dit worden opgegeven. Het adres wordt dan niet toegevoegd in geval het niet kan worden gevonden:
[url]&key=[key]&action=SUBSCRIBE&l=100359&guid=SANDBOX_001

Of met adres parameters:
[url]&key=[key]&action=SUBSCRIBE&l=100359&e=sandbox@mailinglijst.nl&n=sandbox

Bij het toevoegen van een adres waarvan geen &n= (achternaam) is meegegeven wordt het emailadres als achternaam gebruikt.

Extra parameters bij actie=SUBSCRIBE
&optin=  
0: adres wordt direct geoptind (default), of
1: adres ontvangt optinbericht

&welcome=  
0: adres ontvangt geen bevestigingsmail (default), of
1: adres ontvangt bevestigingsmail (geldt alleen als optin=0 (default))

Ad UNSUBSCRIBE (Afmelden)
Bij een afmeld- actie is minimaal het e-mailadres/adresnummer/adres guid en het lijstnummer benodigd.

Om een adres af te melden van een lijst kan worden gekozen voor:
[url]?key=[key]&action=UNSUBSCRIBE&l=100359&e=sandbox@mailinglijst.nl

Indien het unieke adresnummer (guid) bekend is kan dit worden opgegeven:
[url]&key=[key]&action=UNSUBSCRIBE&l=100359&guid=SANDBOX_001

Of met adres parameters:
[url]&key=[key]&action=UNSUBSCRIBE&l=100359&e=sandbox@mailinglijst.nl

Ad EDIT (wijzigen)
Bij een wijzig- actie is minimaal het e-mailadres/adres guid vereist

Om een adres te wijzigen:
[url]?key=[key]&a=1&action=EDIT&guid=SANDBOX_001

of

[url]?key=[key]&a=1&action=EDIT&e=sandbox@mailinglijst.nl

Gevolgd door één of meerdere parameters .

Indien de &guid wordt gebruikt om het adres te identificeren, kan ook met &e= het e-mailadres worden gewijzigd indien het nog niet al voorkomt in de database. Het is mogelijk om rubrieken en vrije velden mee te sturen. Rubrieken en vrije velden moeten al eerder in MailingLijst zijn aangemaakt. Meerdere rubrieken/velden worden met een puntcomma gescheiden. Zie verder Parameters. Indien de OWNER-code wordt meegegeven (&owner=xxx) worden bestaande rubrieken/velden bij het adres van deze owner eerst verwijderd en de meegegeven rubrieken/velden toegekend.

Ad GET (opvragen)
Alle relevante gegevens van een enkel adres kunnen worden opgevraagd (inclusief verzendhistorie, bouncehistorie enzovoort).

[url]?key=[key]&action=GET&e=sandbox@mailinglijst.nl

Of via de GUID: [url]?key=[key]&action=GET&guid=ML__12345l

De structuur van de succesvolle GET-RESPONSE is afwijkend en bevat naast de standaard response ook een uitgebreide XML-adresstructuur.

Ad BLACKLISTADD/BLACKLISTDELETE
Voegt een adres toe aan de BLACKLIST zodat deze niet meer door MailingLijst kan worden gemaild.

[url]?key=[key]&action=BLACKLISTADD&e=sandbox@mailinglijst.nl

[url]?key=[key]&action=BLACKLISTDELETE&e=sandbox@mailinglijst.nl

Ad LISTGET
Vraagt alle lijstinformatie op, inclusief lijstcodes en lijstvelden.

[url]?key=[key]&action=LISTGET&l=[lijstnummer]

Ad LISTCODEGROUP
Vraagt alle actieve codes van bepaalde codegroep, bijv. talen

[url]?key=[key]&action=LISTCODEGROUP&group=[group]

Ad BODYPOST
Bij het posten van een html wordt in MailingLijst automatisch een nieuwe mailing aangemaakt.

[url]?key=[key]&action=BODYPOST&n=[mailingnaam]&d=[omschrijving]&s=[onderwerpregel]&a=[accountnummer]