Handleidingen

API

in Algemeen Trefwoorden: aanmeldenapimailinglijst

MailingLijst biedt de mogelijkheid om via een aanmeldformulier, gekoppeld aan uw website, inschrijvingen automatisch in MailingLijst te verwerken. Naast inschrijvingen via een aanmeldformulier bestaat ook de MailingLijst API. Deze API is ontwikkeld voor webbouwers die inschrijvingen voor bijvoorbeeld de digitale nieuwsbrief via een andere route dan het MailingLijst aanmeldformulier willen laten lopen.

De API is onder andere geschikt voor:

  • Aanmelding via flash websites
  • Inschrijving via reserveringsformulieren
  • Formulieren volledig in eigen huisstijl
  • Aanmelding met alleen een e-mailadres


Voor het inrichten van de API is technische kennis vereist. Wij adviseren om dit door de webbouwer te laten doen. Indien gewenst kan EM-Cultuur hierin (uiteraard) ondersteunen.

Een voorbeeld van de MailingLijst API op de Orkater website:

api

Technische specificaties

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

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

  • De url heeft een KEY-parameter (GUID) die moet overeenkomen met die van de klantgegevens (member).
  • 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).
  • De klant moet rechten hebben om on-line ACTIONS te kunnen uitvoeren. Dit is wordt ingesteld in het MailingLijst CMS per action.


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.

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 www.mailinglijst.nl:
Inlognaam: demo
Account: sandbox
Wachtwoord: S@ndb0x!!!


De [url] heeft een action-parameter:

  • 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 mailing body


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=
1: adres wordt direct geoptind (default), of
0: adres ontvangt optinbericht

&welcome=
0: adres ontvangt geen bevestigingsmail (default), of
1: adres ontvangt bevestigingsmail (geldt alleen als optin=1 (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]

XML retour

Het responsdocument retourneert:

  • De gegevens van de aanroep
  • De gegevens van de betreffende klant/member
  • De unieke code van het betreffende adres (guid)
  • De resultaatcode en een uitleg
  • De transactiedatum


De structuur (xml-schema) van de api-respons wordt actueel gedocumenteerd op http://www.mailinglijst.eu/xml/api.xsd.

Bij GET-acties (opvragen adresgegevens) wordt de adresinformatie onder in het responsedocument toegevoegd. De structuur hiervan staat beschreven in http://www.adrez.nl/xml/adrez_import3.xsd.

Voorbeeld respons
<!–response from MailingLijst-API © EM-Cultuur 2010 –>
<!—(technical) documentation: –>
<api>
<url>www.mailinglijst.eu/api/?key=xxx&action=SUBSCRIBE
&l=100359&e=sandbox@mailinglijst</url>
<referrer>192.168.0.1</referrer>
<member>Demonstratie</member>
<member_id>3476</member_id>
<address_guid>SANDBOX_001</address_guid>
<responsecode>406</responsecode>
<description>emailaddress not valid</description>
<date>12-31-2010 23:59:59</date>
<listcodes owner=”DEMO” deleted=”2”>
<listcode>
<listcode_id>104141</listcode_id>
<code_name>Familie</code_name>
<content />
<responsecode>200</responsecode>
<description>listcode assigned</description>
</listcode>
</listcodes>
<listfields owner=”DEMO” deleted=”1”>
<listfield>
<listcode_id>104143</listcode_id>
<code_name>Welke informatie wilt je ontvangen?</code_name>
<content>Alles</content>
<responsecode>200</responsecode>
<description>listcode assigned</description>
</listfield>
</listfields>
</api>


Resultaat codes

0 UNKNOWN onbekende fout

  • 200 OK gewenste actie is met succes verwerkt
  • 401 VALIDATION actie is niet toegestaan (sleutel, ip-nummer etc)
  • 404 NOTFOUND actie/parameter is onjuist/niet gevonden
  • 406 UNACCEPTABLE gegevens, url of parameter is onjuist
  • 409 CONFLICT opgegeven parameters conflicteren
  • 500 ERROR er is een fout opgetreden tijdens de verwerking van de actie


In het description veld wordt waar zinvol een toelichting gegeven op de resultaatcode.


Parameters

Validatie/beveiliging parameters
?key=
Unieke sleutel van de klant (member)
Te vinden onder Klantenomgeving (onderaan)
Veldlengte: n.v.t.
Veldtype: GUID

&action=
Gewenste actie (SUBSCRIBE, UNSUBSCRIBE, EDIT)
Veldlengte: n.v.t.
Veldtype: tekst

&a=
Account-nummer (voor MailingLijst-licentie met Multi-account)
Veldlengte: n.v.t. (max. 2147483647)
Veldtype: numeriek

&group=
Groep code (alleen voor actie LISTCODEGROUP)
Veldlengte: n.v.t.
Veldtype: tekst

Vullen met:
LANGUAGES = lijst met talen
COUNTRIES = lijst met landen
GENDER = lijst met geslacht

Adres-parameters
&guid=
Uniek adresnummer (address_GUID)
Veldlengte: 20
Veldtype: GUID

&id=
Adresnummer (address_ID)
Veldlengte: n.v.t. (max. 2147483647)
Veldtype: numeriek

&e=
E-mailadres
Veldlengte: 255
Veldtype: tekst

&fn=
Voornaam (first_name)
Veldlengte: 80
Veldtype: tekst

&np=
Tussenvoegsel (name_prefix)
Veldlengte: 40
Veldtype: tekst

&n=
Naam (name)
Veldlengte: 80
Veldtype: tekst

&o=
Organisatie
Veldlengte: 200
Veldtype: tekst

&g=
Geslacht (gender)
Veldlengte: n.v.t.
Veldtype: numeriek of tekst

Vullen met:
101 = organisatie (reageert ook op O of ORGANISATIE)
102 = man (reageert ook op M, MAN of HEER)
103 = vrouw (reageert ook op V, VROUW of MEVROUW)
105 = onbekend

Onbekend (105) wordt aangenomen als de ingevulde gegevens niet overeenkomt met andere gegevens (101, 102 of 103)

Lijst met geslacht is opvraagbaar met action = LISTCODEGROUP en group = GENDER.

&s=
Straat
Veldlengte: 80
Veldtype: tekst

&num=
Huisnummer (number)
Veldlengte: 20
Veldtype: tekst

&z=
Postcode (zipcode)
Veldlengte: 20
Veldtype: tekst

&c=
Plaats (city)
Veldlengte: 80
Veldtype: tekst

&cnt=
Land (country)
Veldlengte: 255
Veldtype: tekst

Reageert alleen op tekst die identiek zijn aan die zijn gedefinieerd in MailingLijst (niet hoofdlettergevoelig). Nederland wordt standaard aangenomen als het veld leeg of onbekend is.

Lijst met alle landen is opvraagbaar met action = LISTCODEGROUP en group = COUNTRIES

&m=
Mobiel
Veldlengte: 255
Veldtype: tekst

&p=
Telefoonnummer (phone)
Veldlengte: 255
Veldtype: tekst

&th=
Text/html
Veldlengte: 1
Veldtype: tekst

Vullen met:
H = HTML (deze wordt standaard aangenomen)
T = TEKST

&i=
Is actief
Veldlengte: 1
Veldtype: ja/nee

Vullen met:
1 = actief (deze wordt standaard aangenomen)
0 = inactief

&lang=
Taal (language)
Veldlengte: 255
Veldtype: tekst

Reageert alleen op tekst die identiek zijn aan die zijn gedefinieerd in MailingLijst (niet hoofdlettergevoelig). Nederlands wordt standaard aangenomen als het veld leeg of onbekend is.

Lijst met alle talen is opvraagbaar met action = LISTCODEGROUP en group = LANGUAGES.

&so=
Bron (source)
Veldlengte: 100
Veldtype: tekst

&ic=
Importcode
Veldlengte: 100
Veldtype: tekst

&sy=
Relatienummer (sync_ID)
Veldlengte: 100
Veldtype: tekst

&guid, &id of &e zijn verplicht bij adresparameters.

Code parameters
De code-parameters gebruiken puntcomma, comma en dubbelepunt voor scheiding. Deze mogen dus niet voorkomen in veldnamen/veldwaarden.

&lc=
Rubrieken (listcodes)
De rubrieken worden gescheiden met puntcomma:

[url]&key=[key]&action=UNSUBSCRIBE&l=100359&e=sandbox@mailinglijst.nl&lc=[listcode 1];[listcode 2];[listcode 3]

&xf =
Vrije velden (extra fields)
Veldlengte per vrije veld: 255
Veldtype: tekst

De velden worden gescheiden met puntcomma.
Veld-guid en veldwaarde wordt gescheiden door een comma.

Om meerdere waarden binnen een veldwaarde op te kunnen geven wordt binnen de gescheiden met een dubbele punten (:)
[url]&key=[key]&action=UNSUBSCRIBE&l=100359&e=sandbox@mailinglijst.nl

&xf=[field 1],[value 1];[field 2], [value 2];[field 3],[value 3]:[en ook value 4]; [field 5], [value 5]

Verwijderen van codes?
Om rubrieken en vrije velden te kunnen verwijderen wordt er gebruik gemaakt van het OWNER veld. Dus het owner veld van de betreffende rubrieken en vrije velden vul je met bijvoorbeeld ‘EMC’. Vervolgens gebruik je dit ook in de URL die de API aanroept (&owner=EMC). De API kijkt dan alleen naar de velden die toegekend moeten worden, de andere velden worden verwijderd.

Formaten
Datum: yyyy-MM-dd (1987-06-01) of dd-MM-yyyy (01-06-1987)
Numeriek: maximaal 2147483647
Vink of ja/nee: 1 (= ja) of 0 (= nee)

&owner=
OWNER van de code. Deze zorgt dat oude codes eerst worden verwijderd.

Extra parameters
&optin=
Optin
Veldlengte: 1
Veldtype: ja/nee
Vullen met:
1 = adres wordt direct, zonder bericht, geoptind (default)
0 = adres wordt niet geoptind

&welcome=
Welkomsmail
Veldlengte: 1
Veldtype: ja/nee
Vullen met:
0 = adres ontvangt geen welkomsmail (deze wordt standaard aangenomen)
1 = adres ontvangt welkomsmail (geldt alleen als &optin=0)

Mailing parameters (bodypost)
&n=
Naam
Veldlengte: 150
Veldtype: tekst

&s=
Onderwerpregel (subject)
Veldlengte: 150
Veldtype: tekst

&d=
Omschrijving (description)
Veldlengte: 500
Veldtype: tekst

&o=
Eigenaar (owner)
Veldlengte: 20
Veldtype: tekst

&stats_links=
Linkstatistieken
Veldlengte: 1
Veldtype: ja/nee
Vullen met:
0 = de links worden niet aangevinkt voor de statistieken (deze wordt standaard aangenomen)
1 = de links worden aangevinkt voor de statistieken

&m=
Mailingnummer (voor updaten van een mailing)
Veldtype: numeriek


Code sample

Private Sub Online()
Dim webRequest As HttpWebRequest
Dim webResponse As HttpWebResponse
Dim ioReader As StreamReader
Dim xmlResponse As XmlDocument
Dim strResults As String
Dim strLink As String
Try
strLink = “http://www.mailinglijst.eu/api/?key=[key]&action=[action]”

webRequest = DirectCast(System.Net.WebRequest.Create(strLink), HttpWebRequest)
webResponse = DirectCast(webRequest.GetResponse(), HttpWebResponse)
ioReader = New StreamReader(webResponse.GetResponseStream())
strResults = ioReader.ReadToEnd()

Me.litResult.Text = strResults

‘Do something with response from API

Catch ex As Exception
‘Catch exception
End Try
End Sub

Private Sub PostBody()
Dim strUrl As String
Dim webResp As HttpWebResponse
Dim webReq As HttpWebRequest
Dim ioWriter As StreamWriter
Dim ioReader As StreamReader
Dim strResponse As String
Try
strUrl = “http://dev.mailinglijst.eu/api/?key=[key]&action=BODYPOST&s=[onderwerpregel]&n=[naam]&d=[omschrijving]&o=[eigenaar]”

webReq = WebRequest.Create(strUrl)
webReq.Method = “POST”
webReq.ContentType = “text/html;charset=””iso-8859-15″””
webReq.Accept = “text/html”

ioWriter = New StreamWriter(webReq.GetRequestStream())
ioWriter.Write(txtBody.Text)
ioWriter.Close()

webResp = webReq.GetResponse()

ioReader = New StreamReader(webResp.GetResponseStream())
strResponse = ioReader.ReadToEnd()

‘ Do something with response from API

Catch ex As Exception
‘ Catch exception
End Try
End Sub