API documentatie

Vragen of opmerkingen horen we graag! Mail naar api@laposta.nl.

De in de voorbeelden gebruikte API-key is beschikbaar om mee te testen.

De Laposta API is opgezet volgens het REST principe. Alle antwoorden van de API, inclusief de foutmeldingen, zijn in JSON formaat.

In de API staat het toevoegen en uitlezen van relaties centraal. Hiermee is het onder andere mogelijk Laposta te synchroniseren met een ander systeem, zoals een CMS of een CRM. Een andere veelgebruikte toepassing is het automatisch toevoegen van relaties aan Laposta, bijvoorbeeld bij het doen van een bestelling in een webshop.

Voor partners is het ook mogelijk accounts aan te maken via de API, zodat de opzet van accounts voor klanten geheel zonder onze tussenkomst kan verlopen.

Om het programmeren met de API makkelijker te maken, zijn er bibliotheken in php en .NET (C#) beschikbaar.

API basis URL

De API is beschikbaar via http en https. Vanuit het oogpunt van veiligheid adviseren we u om met https te werken.

http://api.laposta.nl/
https://api.laposta.nl/

Beschikbare URL patronen

/v2/member
/v2/member/{member_id}

Authenticatie

Bij elke aanvraag moet de API-key van het account worden opgegeven. Deze kunt u vinden door in te loggen en dan naar rechtsboven op 'Toegang & Abonnement' te klikken, en dan naar 'Koppelingen - API' te gaan.

Authenticatie gaat via Basic Authentication. De API-key wordt gebruikt als username; een wachtwoord is niet nodig.

Voorbeeld aanvraag

$ curl https://api.laposta.nl/v2/member?list_id=BaImMu3JZA \
  -u JdMtbsMq2jqJdQZD9AHC:

Met behulp van de '-u' parameter kunt u de API-key met Basic Authentication doorgeven. Door een dubbele punt achter de key te zetten wordt voorkomen dat er om een wachtwoord wordt gevraagd.

Ratelimiting

Om onze systemen te beschermen wordt het aantal aanvragen per tijdseenheid beperkt. Als u een limiet bereikt dan krijgt u hiervan een melding van onze server. Bij deze melding wordt ook aangegeven na hoeveel seconden een volgende aanvraag weer mogelijk is.

Voor gratis accounts geldt een limiet van 30 aanvragen per minuut. Voor betaalde accounts is de limiet 120 aanvragen per minuut.

Probeer zoveel mogelijk informatie te cachen! Het is bijvoorbeeld niet handig/nodig om een aanmeldformulier te maken, en dan bij elke pageview de informatie over de velden op te halen.

Als de limiet bereikt wordt

Bereikt u de limiet, dan zal de server reageren met een statuscode 429 (Too Many Requests). De server zal ook een Retry-After header meesturen, met daarin het aantal seconden dat gewacht moet worden tot de volgende aanvraag weer mogelijk is.

Foutmeldingen

Onze API gebruikt zoveel mogelijk standaard HTTP statuscodes om aan te geven hoe een aanvraag is verlopen. Codes in de 2xx reeks betekenen dat een aanvraag succesvol is verlopen, codes in de 4xx reeks dat er een fout was in de aanlevering van informatie (bijvoorbeeld een missende parameter). Codes in de 5xx reeks tenslotte betekenen dat er aan onze kant iets mis ging.

Alle foutmeldingen zijn in JSON formaat en bevatten een aanduiding van het type fout, een melding in gewone taal, en eventueel een code en een parameter (om aan te geven waar de fout zat).

Overzicht gebruikte HTTP statuscodes

200 OK	Alles in orde
201 Created	Alles in orde, object aangemaakt
400 Bad Request	Incomplete input
401 Unauthorized	Er werd geen geldige API-key meegegeven
402 Request Failed	Input was in orde, maar aanvraag is niet verwerkt
404 Not Found	Het opgevraagde item bestaat niet
429 Too Many Requests	Het maximale aantal aanvragen binnen de tijdseenheid is bereikt
500 Server Error	Fout aan de kant van Laposta

Overzicht attributen in foutmelding

type	het soort fout. Dit kan zijn invalid_request bij een fout in de aanroep van de URL, invalid_input bij een fout in de aangeleverde gegevens, of internal bij een fout in ons systeem.
message	uitleg van de fout in voor mensen begrijpelijke taal.
code	een nummerieke aanduiding van de fout (optioneel, zie hieronder).
parameter	de parameter die de fout betreft (optioneel).

Overzicht codes in foutmelding

201	De parameter is leeg
202	De syntax van de parameter is niet correct
203	De parameter is onbekend
204	De parameter komt al voor
205	De parameter is geen getal
206	De parameter is geen boolean (true/false)
207	De parameter is geen datum
208	De parameter is geen e-mailadres
209	De parameter is geen URL
999	De parameter bevat een andere fout

Voorbeeld Error object

{
    "error": {
        "type": "invalid_input",
        "message": "Email: invalid address",
        "code": 208,
        "parameter": "email"
    }
}

Lijsten

Met dit onderdeel kunt u lijsten opvragen, toevoegen, wijzigen, verwijderen en leegmaken.

URL patronen

/v2/list
/v2/list/{list_id}
/v2/list/{list_id}/members

Het list object

Velden

list_id:	Het id van deze lijst
created:	Moment van aanmaken
modified:	Moment van laatste wijziging
state:	De status van de lijst: `active` of `deleted`
name:	Naam die aan deze lijst gegeven is
remarks:	Eventuele opmerkingen
subscribe_notification_email:	E-mailadres waarnaar een notificatie wordt verstuurd bij een aanmelding
unsubscribe_notification_email:	E-mailadres waarnaar een notificatie wordt verstuurd bij een afmelding
members:	Informatie over het aantal actieve, afgemelde en opgeschoonde relaties

Voorbeeld list object

{
    "list": {
        "list_id": "BaImMu3JZA",
        "created": "2012-02-18 11:42:38",
        "modified": "2012-06-02 14:07:20",
	"state": "active",
        "name": "Testlijst",
        "remarks": "Een lijst om mee te testen.",
	"subscribe_notification_email": "aanmeldingen@example.net",
	"unsubscribe_notification_email": "afmeldingen@example.net",
	"members": {
		"active": 1232,
		"unsubscribed": 113,
		"cleaned": 14 
        }
    }
}

Lijst toevoegen

Als er iets niet klopt aan de meegegeven parameters dan wordt bij de foutmelding een code weergegeven. Deze kunt u in combinatie met de variabele 'parameter' gebruiken om een melding aan de gebruiker te tonen. Zie hierboven bij Foutmeldingen wat de codes betekenen.

Parameters

name (verplicht):	Een naam voor deze lijst
remarks:	Eventuele opmerkingen
subscribe_notification_email:	E-mailadres waarnaar notificaties bij aanmeldingen kunnen worden verzonden
unsubscribe_notification_email:	E-mailadres waarnaar notificaties bij afmeldingen kunnen worden verzonden

Definitie

POST https://api.laposta.nl/v2/list

Voorbeeld aanvraag

$ curl https://api.laposta.nl/v2/list \
  -u JdMtbsMq2jqJdQZD9AHC: \
  -d name=Testlijst \
  '-d remarks=Een lijst om mee te testen' \
  -d subscribe_notification_email=aanmeldingen@example.net \
  -d unsubscribe_notification_email=afmeldingen@example.net

Voorbeeld antwoord

{
    "list": {
        "list_id": "BaImMu3JZA",
        "created": "2012-02-18 11:42:38",
        "modified": "2012-06-02 14:07:20",
	"state": "active",
        "name": "Testlijst",
        "remarks": "Een lijst om mee te testen.",
	"subscribe_notification_email": "aanmeldingen@example.net",
	"unsubscribe_notification_email": "afmeldingen@example.net",
	"members": {
		"active": 0,
		"unsubscribed": 0,
		"cleaned": 0 
        }
    }
}

Lijst opvragen

Alle informatie over een lijst.

Parameters

list_id (verplicht):

Het id van de lijst

Definitie

GET https://api.laposta.nl/v2/list/{list_id}

Voorbeeld aanvraag

$ curl https://api.laposta.nl/v2/list/BaImMu3JZA \
  -u JdMtbsMq2jqJdQZD9AHC:

Voorbeeld antwoord
{
    "list": {
	"list_id": "BaImMu3JZA",
	"created": "2012-02-18 11:42:38",
	"modified": "2012-06-02 14:07:20",
	"state": "active",
	"name": "Testlijst",
	"remarks": "Een lijst om mee te testen.",
	"subscribe_notification_email": "aanmeldingen@example.net",
	"unsubscribe_notification_email": "afmeldingen@example.net"
	"members": {
		"active": 1232,
		"unsubscribed": 113,
		"cleaned": 14 
	}
    }
}

Lijst wijzigen

U hoeft alleen de velden die gewijzigd moeten worden in de aanvraag mee te sturen. Velden die niet worden genoemd houden hun huidige waarde. Zodra een veld wordt genoemd wordt het wel gecontroleerd, en kan dus voor een foutmelding zorgen. Bij deze foutmelding wordt een code weergegeven. Deze kunt u in combinatie met de variabele 'parameter' gebruiken om een melding aan de gebruiker te tonen. Zie hierboven bij Foutmeldingen wat de codes betekenen.

Parameters

list_id (verplicht):	Het id van de lijst die gewijzigd moet worden
name:	Een naam voor deze lijst
remarks:	Eventuele opmerkingen
subscribe_notification_email:	E-mailadres waarnaar notificaties bij aanmeldingen kunnen worden verzonden
unsubscribe_notification_email:	E-mailadres waarnaar notificaties bij afmeldingen kunnen worden verzonden

Definitie

POST https://api.laposta.nl/v2/list/{list_id}

Voorbeeld aanvraag

Dit voorbeeld wijzigt de naam.

$ curl https://api.laposta.nl/v2/list/BaImMu3JZA \
  -u JdMtbsMq2jqJdQZD9AHC: \
  -d name=Klanten

Voorbeeld antwoord

{
    "list": {
        "list_id": "BaImMu3JZA",
        "created": "2012-02-18 11:42:38",
        "modified": "2012-06-02 14:07:20",
	"state": "active",
        "name": "Klanten",
        "remarks": "Een lijst om mee te testen.",
	"subscribe_notification_email": "aanmeldingen@example.net",
	"unsubscribe_notification_email": "afmeldingen@example.net",
	"members": {
		"active": 1232,
		"unsubscribed": 113,
		"cleaned": 14 
        }
    }
}

Lijst verwijderen

Hiermee verwijdert u een lijst definitief. Als de lijst niet bestaat wordt een foutmelding gegeven. Als antwoord krijgt u weer een list object, maar nu met state 'deleted'. Hierna is deze lijst niet nogmaals op te vragen.

Parameters

list_id (verplicht):

Het id van de lijst

Definitie

DELETE https://api.laposta.nl/v2/list/{list_id}

Voorbeeld aanvraag

$ curl https://api.laposta.nl/v2/list/BaImMu3JZA \
  -u JdMtbsMq2jqJdQZD9AHC: \
  -X DELETE

Voorbeeld antwoord

{
    "list": {
        "list_id": "BaImMu3JZA",
        "created": "2012-02-18 11:42:38",
        "modified": "2012-06-02 14:07:20",
	"state": "deleted",
        "name": "Klanten",
        "remarks": "Een lijst om mee te testen.",
	"subscribe_notification_email": "aanmeldingen@example.net",
	"unsubscribe_notification_email": "afmeldingen@example.net",
	"members": {
		"active": 1232,
		"unsubscribed": 113,
		"cleaned": 14 
        }
    }
}

Alle lijsten opvragen

Alle lijsten in een array van list objecten. De list objecten zijn opgenomen in een array met de naam 'data'.

Parameters

Er hoeven geen parameters te worden meegegeven.

Definitie

GET https://api.laposta.nl/v2/list

Voorbeeld aanvraag

$ curl https://api.laposta.nl/v2/list \
  -u JdMtbsMq2jqJdQZD9AHC:

Voorbeeld antwoord

{
    "data": [
        {
            "list": {
                "list_id": "BaImMu3JZA",
                "created": "2012-02-18 11:42:38",
                "modified": "2012-06-02 14:07:20",
		"state": "active",
                "name": "Testlijst",
                "remarks": "Een lijst om mee te testen.",
        	"subscribe_notification_email": "aanmeldingen@example.net",
        	"unsubscribe_notification_email": "afmeldingen@example.net"
		"members": {
			"active": 1232,
			"unsubscribed": 113,
			"cleaned": 14 
		}
            }
	},
        {
            "list": {
                "list_id": "Z87Jajj9Ak",
                "created": "2012-03-30 12:23:46",
                "modified": "2012-04-10 13:33:21",
		"state": "active",
                "name": "Een andere lijst",
                "remarks": "Klanten",
        	"subscribe_notification_email": "aanmeldingen@example.net",
        	"unsubscribe_notification_email": "afmeldingen@example.net"
		"members": {
			"active": 8182,
			"unsubscribed": 205,
			"cleaned": 56 
		}
            }
	}
    ]
}

Lijst leegmaken

Hiermee verwijdert u alle actieve relaties uit een lijst definitief, maar niet de lijst zelf. Als de lijst niet bestaat wordt een foutmelding gegeven. Als antwoord krijgt u weer een list object.

Parameters

list_id (verplicht):

Het id van de lijst

Definitie

DELETE https://api.laposta.nl/v2/list/{list_id}/members

Voorbeeld aanvraag

$ curl https://api.laposta.nl/v2/list/BaImMu3JZA/members \
  -u JdMtbsMq2jqJdQZD9AHC: \
  -X DELETE

Voorbeeld antwoord

{
    "list": {
        "list_id": "BaImMu3JZA",
        "created": "2012-02-18 11:42:38",
        "modified": "2012-06-02 14:07:20",
	"state": "active",
        "name": "Klanten",
        "remarks": "Een lijst om mee te testen.",
	"subscribe_notification_email": "aanmeldingen@example.net",
	"unsubscribe_notification_email": "afmeldingen@example.net",
	"members": {
		"active": 0,
		"unsubscribed": 0,
		"cleaned": 0 
        }
    }
}

Lijst vullen / aanpassen (bulk)

Deze functie is niet beschikbaar voor gratis accounts.

Hiermee kunt u meerdere relaties gelijktijdig wijzigen en/of toevoegen aan een bestaande lijst. Als de lijst niet bestaat of wanneer verplichte parameters ontbreken krijgt u een foutmelding. Let op: het aanleveren van de data gebeurt middels JSON.

Parameters

list_id (verplicht):

Het id van de lijst

JSON Object

mode (verplicht):	De modus van het verzoek: edit, add, of add_and_edit. In de modus add worden alleen nieuwe relaties toegevoegd en worden gegevens van bestaande relaties genegeerd. In de modus edit worden nieuwe relaties genegeerd en worden gegevens van bestaande relaties gewijzigd. In de modus add_and_edit worden nieuwe relaties toegevoegd en worden gegevens van bestaande relaties gewijzigd.
members (verplicht):	Een array met member objecten. Minimaal 1, maximaal 100.000.

Member Object

member_id (soms verplicht):	Het id OF het emailadres van de relatie. Als dit is opgegeven moet deze voorkomen in de lijst.
email (soms verplicht):	Het e-mailadres van de te wijzigen of toe te voegen relatie. Als member_id ook is opgegeven dan kan hier een nieuw e-mailadres worden opgegeven voor de bestaande relatie.
custom_fields (soms verplicht):	Een JSON object waarbij de key de naam is van het extra veld en de value de waarde is van het extra veld.
source_url:	URL vanwaar de relatie is aangemeld.

Het veld member_id is verplicht als het veld email ontbreekt. Als member_id is opgegeven, dan wordt de bijpassende relatie in de lijst opgezocht om vervolgens bij te werken.
Het veld email is verplicht als het veld member_id ontbreekt. Als er wel een email is opgegeven en geen member_id, dan zoeken we op basis van email een bijpassende relatie in de lijst. Als deze gevonden wordt zullen we deze relatie bijwerken. Als deze niet gevonden wordt zullen we een nieuwe relatie toevoegen.
Een custom field kan verplicht zijn als u verplichte velden in de lijst heeft staan. Een custom field is nooit verplicht voor een bestaande relatie.
Voor relaties die via deze weg worden toegevoegd stellen wij het IP-adres gelijk met de server waarvan het verzoek komt.

Definitie

POST https://api.laposta.nl/v2/list/{list_id}/members

Voorbeeld aanvraag

$ curl --json '{json_string}' https://api.laposta.nl/v2/list/BaImMu3JZA/members \
  -u JdMtbsMq2jqJdQZD9AHC: \
  -X POST

De {json_string} moet een goed opgemaakte JSON string zijn die voldoet aan de voorwaarden zoals beschreven bij 'JSON OBJECT'. Een leesbaar voorbeeld:

{
    "mode": "add",
    "members": [
        {
            "email": "member1@example.org"
        },
        {
            "member_id": "9978ydioiZ",
            "email": "member2@example.org"
        },
        {
            "email": "member3@example.org",
            "custom_fields": {
                "my_required_field": "My required field value",
                "my_optional_field": "My optional value"
            }
        }
    ]
}

Voorbeeld antwoord

Allereerst kan er een foutmelding teruggestuurd worden zoals omschreven onder foutmeldingen. Dit gebeurt wanneer het verzoek wordt afgekeurd op basis van de niet of verkeerd meegestuurde list_id, of wanneer de meegestuurde JSON data niet correct is.

Als er geen sprake is van een foutmelding zoals hierboven omschreven sturen wij altijd een succesvolle response volgens het volgende voorbeeld van mode add:

{
    "report": {
        "provided_count": 3,
        "errors_count": 1,
        "skipped_count": 1,
        "edited_count": 0,
        "added_count": 1
    },
    "errors": [
        {
            "provided_data": {
                "email": "member1@example.org"
            },
            "error": {
                "message": "Field my_required_field: cannot be empty",
                "code": 201,
                "parameter": "my_required_field",
                "id": "lRZBQFQdBk",
                "type": "invalid_input"
            }
        }
    ],
    "skipped": [
        {
            "provided_data": {
                "member_id": "9978ydioiZ",
                "email": "member2@example.org",
                "custom_fields": {
                    "my_optional_field": "My optional value"
                }
            },
            "member": {
                "member_id": "9978ydioiZ",
                "list_id": "BaImMu3JZA",
                "email": "member2@example.org",
                "state": "active",
                "signup_date": "2023-01-01 11:58:16",
                "modified": null,
                "confirm_date": null,
                "ip": "198.51.100.10",
                "source_url": "",
                "custom_fields": {
                    "my_required_field": "My required field value",
                    "my_optional_field": ""
                }
            }
        }
    ],
    "edited": [],
    "added": [
        {
            "provided_data": {
                "email": "member3@example.org",
                "custom_fields": {
                    "my_required_field": "My required field value",
                    "my_optional_field": "My optional  value"
                }
            },
            "member": {
                "member_id": "vnvj2cfQ3a",
                "list_id": "BaImMu3JZA",
                "email": "member3@example.org",
                "state": "active",
                "signup_date": "2023-02-07 17:29:33",
                "modified": null,
                "confirm_date": null,
                "ip": "198.51.100.10",
                "source_url": null,
                "custom_fields": {
                    "my_required_field": "My required field value",
                    "my_optional_field": "My optional  value"
                }
            }
        }
    ]
}

Zoals u in bovenstaand voorbeeld kunt zien delen ontvangt u een report en delen wij de aangeleverde member objected op in errors, skipped, edited en added. Deze gegevens ontvangt u altijd van ons, ook als er geen data in zit. Van elke member die wij verwerken, ontvangt u de provided_data en waar mogelijk ook een member object zoals de member op dat moment bij ons in het systeem bekend is. Op deze manier kunt u eenvoudig de toegestuurde lijst vergelijken met de status bij Laposta. Members komen in skipped terecht wanneer deze volgens de opgegeven mode niet verwerkt mogen worden, maar toch meegeleverd zijn.

Velden

Met dit onderdeel kunt u velden van lijsten opvragen, toevoegen en wijzigen.

URL patronen

/v2/field
/v2/field/{field_id}

Het field object

Velden

field_id:	Het id van dit veld
list_id:	Het id van de lijst waartoe het veld behoort
created:	Moment van aanmaken
modified:	Moment van laatste wijziging
state:	De status van dit veld: `active` of `deleted`
name:	Naam van het veld (voor weergave)
tag:	De relatievariabele voor gebruik in campagnes (niet wijzigbaar)
custom_name:	Naam van het veld (voor gebruik bij member api calls)
defaultvalue:	Standaardwaarde (wordt gebruikt bij afwezigheid van dit veld)
datatype:	Het datatype van dit veld (`text`, `numeric`, `date`, `select_single`, `select_multiple`)
datatype_display:	Alleen voor select_single: de gewenste weergave (`select`, `radio`)
options:	Een array van de beschikbare opties (alleen bij `select_single` of `select_multiple`)
options_full:	Een array van de beschikbare opties, inclusief id's (alleen bij `select_single` of `select_multiple`)
required:	Is dit een verplicht veld? (`true` of `false`)
in_form:	Komt dit veld voor in het aanmeldformulier? (`true` of `false`)
in_list:	Komt dit veld voor bij het bladeren in de lijst? (`true` of `false`)
autocomplete:	De waarde voor het html autocomplete attribuut (`string`)

Voorbeeld field object

{
    "field": {
        "field_id": "Z87ysHha9A",
        "list_id": "BaImMu3JZA",
        "created": "2012-02-18 11:42:38",
        "modified": "2012-06-02 14:07:20",
	"state": "active",
        "name": "Naam",
        "tag": "{{naam}}",
        "custom_name": "naam",
        "defaultvalue": "",
        "datatype": "text",
        "datatype_display": null,
        "required": true,
        "in_form": true,
        "in_list": true,
        "autocomplete": "on"
    }
}

Veld toevoegen

Als er iets niet klopt aan de meegegeven parameters dan wordt bij de foutmelding een code en een melding weergegeven. Zie hierboven bij Foutmeldingen wat de codes betekenen.

Parameters

list_id (verplicht):	Het id van de lijst waartoe het veld behoort
name (verplicht):	Een naam voor dit veld
defaultvalue:	Een eventuele standaardwaarde
datatype (verplicht):	Het datatype: `text`, `numeric`, `date`, `select_single` of `select_multiple`
datatype_display:	Alleen voor select_single: de gewenste weergave (`select`, `radio`)
options:	Welke selectiemogelijkheden zijn er? (Verplicht bij datatypes `select_single` of `select_multiple`). De opties kunnen als array worden meegegeven. Bij het antwoord worden de options herhaald, maar is er ook een extra veld `options_full`. Hierin staan ook de bij de options horende id's genoemd, die eventueel gebruikt kunnen worden om de options later te wijzigen.
required (verplicht):	Is dit een verplicht veld?
in_form (verplicht):	Is het veld te zien in het aanmeldformulier? (`boolean`)
in_list (verplicht):	Is het veld te zien in het overzicht in Laposta? (`boolean`)

Definitie

POST https://api.laposta.nl/v2/field

Voorbeeld aanvraag

curl https://api.laposta.nl/v2/field \
  -u JdMtbsMq2jqJdQZD9AHC: \
  -d list_id=srbhotdwob \
  -d name=Kleur \
  -d defaultvalue=Groen \
  -d datatype=select_single \
  -d datatype_display=radio \
  -d options[]=Rood \
  -d options[]=Groen \
  -d options[]=Blauw \
  -d required=true \
  -d in_form=true \
  -d in_list=true

Voorbeeld antwoord

{
    "field": {
        "field_id": "GeVKetES6z",
        "list_id": "srbhotdwob",
        "created": "2016-06-06 22:24:38",
        "modified": null,
        "state": "active",
        "name": "Kleur",
        "tag": "{{kleur}}",
        "defaultvalue": "Groen",
        "datatype": "select_single",
        "datatype_display": "radio",
        "required": true,
        "in_form": true,
        "in_list": true,
        "is_email": false,
        "autocomplete": "on",
        "options": [
            "Rood",
            "Groen",
            "Blauw"
        ],
        "options_full": [
            {
                "id": 1,
                "value": "Rood"
            },
            {
                "id": 2,
                "value": "Groen"
            },
            {
                "id": 3,
                "value": "Blauw"
            }
        ]
    }
}

Veld opvragen

Alle informatie over een veld.

Parameters

list_id (verplicht):	Het id van de lijst waarbij het veld hoort
field_id (verplicht):	Het id van het op te vragen veld

Definitie

GET https://api.laposta.nl/v2/field/{field_id}

Voorbeeld aanvraag

$ curl https://api.laposta.nl/v2/field/gt2Em8vJwi?list_id=BaImMu3JZA \
  -u JdMtbsMq2jqJdQZD9AHC:

Voorbeeld antwoord
{
    "field": {
        "field_id": "gt2Em8vJwi",
        "list_id": "BaImMu3JZA",
        "created": "2012-02-18 11:42:38",
        "modified": "2012-06-02 14:07:20",
	"state": "active",
        "name": "Naam",
        "tag": "{{naam}}",
        "custom_name": "naam",
        "defaultvalue": "",
        "datatype": "text",
        "datatype_display": null,
        "required": true,
        "in_form": true,
        "in_list": true,
        "autocomplete": "on"
    }
}

Veld wijzigen

U hoeft alleen de onderdelen die gewijzigd moeten worden in de aanvraag mee te sturen. Onderdelen die niet worden genoemd houden hun huidige waarde. Zodra een onderdeel wordt genoemd wordt het wel gecontroleerd, en kan dus voor een foutmelding zorgen. Bij deze foutmelding wordt een code weergegeven met een melding. Zie hierboven bij Foutmeldingen wat de codes betekenen.

Let op: het wijzigen van het datatype verwijdert alle gegevens van dat veld voor relaties.

Parameters

list_id (verplicht):	Het id van de lijst waartoe het veld behoort
name:	Een naam voor dit veld
datatype:	Het datatype van dit veld (`text`, `numeric`, `date`, `select_single`, `select_multiple`)
datatype_display:	Alleen voor select_single: de gewenste weergave (`select`, `radio`)
options:	Welke selectiemogelijkheden zijn er? Array met alleen de waardes. Let op: deze lijst vervangt in zijn geheel de bestaande options; voor het wijzigen van velden die al in gebruik zijn is het beter `options_full` te gebruiken. (Alleen mogelijk bij datatypes `select_single` of `select_multiple`)
options_full:	Welke selectiemogelijkheden zijn er? Array met per optie zowel de waarde (`value`) als het id (`id`). Als id's overeenkomen wordt de bijbehorende optie gewijzigd. (Alleen mogelijk bij datatypes `select_single` of `select_multiple`)
defaultvalue:	Standaardwaarde (wordt gebruikt bij afwezigheid van dit veld)
required:	Is dit een verplicht veld?
in_form:	Is het veld te zien in het aanmeldformulier? (`boolean`)
in_list:	Is het veld te zien in het overzicht in Laposta? (`boolean`)

Definitie

POST https://api.laposta.nl/v2/field/{field_id}

Voorbeeld aanvraag

Dit voorbeeld maakt het veld niet meer verplicht.

$ curl https://api.laposta.nl/v2/field/hsJ5zbDfzJ \
  -u JdMtbsMq2jqJdQZD9AHC: \
  -d list_id=BaImMu3JZA \
  -d required=false

Voorbeeld antwoord

{
    "field": {
        "field_id": "hsJ5zbDfzJ",
        "list_id": "BaImMu3JZA",
        "created": "2012-10-31 11:55:50",
        "modified": "2012-10-31 12:05:44",
        "state": "active",
        "name": "Leeftijd",
        "tag": "{{leeftijd}}",
        "custom_name": "leeftijd",
        "defaultvalue": "",
        "datatype": "text",
        "datatype_display": null,
        "required": false,
        "in_form": true,
        "in_list": true,
        "autocomplete": "on"
    }
}

Veld verwijderen

Hiermee verwijdert u een veld definitief. Als het veld niet bestaat wordt een foutmelding gegeven. Als antwoord krijgt u weer een veld object, maar nu met state 'deleted'. Hierna is dit veld niet nogmaals op te vragen.

Parameters

field_id (verplicht):	Het id van het te verwijderen veld
list_id (verplicht):	Het id van de lijst waartoe het veld behoort

Definitie

DELETE https://api.laposta.nl/v2/field/{field_id}

Voorbeeld aanvraag

$ curl https://api.laposta.nl/v2/field/lxwc8OyD3a?list_id=BaImMu3JZA \
  -u JdMtbsMq2jqJdQZD9AHC: \
  -X DELETE

Voorbeeld antwoord

{
    "field": {
        "field_id": "lxwc8OyD3a",
        "list_id": "BaImMu3JZA",
        "created": "2012-10-30 21:44:40",
        "modified": null,
        "state": "deleted",
        "name": "Lievelingskleur",
        "tag": "{{lievelingskleur}}",
        "custom_name": "lievelingskleur",
        "defaultvalue": "",
        "datatype": "text",
        "datatype_display": null,
        "required": false,
        "in_form": true,
        "in_list": true,
        "autocomplete": "on"
    }
}

Alle velden van een lijst opvragen

Alle velden van een lijst in een array van field objecten. De field objecten zijn opgenomen in een array met de naam 'data'.

Parameters

list_id (verplicht):

Het id van de lijst waarbij de velden horen

Definitie

GET https://api.laposta.nl/v2/field

Voorbeeld aanvraag

$ curl https://api.laposta.nl/v2/field?list_id=BaImMu3JZA \
  -u JdMtbsMq2jqJdQZD9AHC:

Voorbeeld antwoord

{
    "data": [
        {
	    "field": {
		"field_id": "Z87ysHha9A",
		"list_id": "BaImMu3JZA",
		"created": "2012-02-18 11:42:38",
		"modified": "2012-06-02 14:07:20",
		"state": "active",
		"name": "Naam",
		"tag": "{{naam}}",
		"custom_name": "naam",
		"defaultvalue": "lezer",
		"datatype": "text",
		"required": true,
		"in_form": true,
		"in_list": true,
		"autocomplete": "on"
	    }
	},
        {
	    "field": {
		"field_id": "9hj8HA_8A2",
		"list_id": "BaImMu3JZA",
		"created": "2012-03-28 20:12:02",
		"modified": "2012-03-28 20:13:10",
		"state": "active",
		"name": "Leeftijd",
		"tag": "{{leeftijd}}",
		"custom_name": "leeftijd",
		"defaultvalue": "onbekend",
		"datatype": "date",
		"required": true,
		"in_form": true,
		"in_list": true,
		"autocomplete": "on"
	    }
	}
    ]
}

Relaties

Met dit onderdeel kunt u relaties opvragen, toevoegen en wijzigen.

Als parameter heeft u steeds een list_id nodig. Deze kunt u vinden door in te loggen, en dan naar de betreffende lijst te gaan onder 'Relaties'. Vervolgens klikt u op de tab 'Kenmerken lijst'. Aan de rechterzijde ziet u daar het ID staan.

URL patronen

/v2/member
/v2/member/{member_id}

Het member object

Velden

member_id:	Het id van dit member object
list_id:	Het id van de bijbehorende lijst
email:	Het e-mail adres
state:	De huidige status van deze relatie: `active`, `unsubscribed`, `unconfirmed` of `cleaned`
signup_date:	Moment van aanmelding, formaat YYYY-MM-DD HH:MM:SS
modified:	Moment van laatste wijziging, formaat YYYY-MM-DD HH:MM:SS
ip:	IP vanwaar de relatie is aangemeld
source_url:	URL vanwaar de relatie is aangemeld
custom_fields:	Een object met de waarde van alle extra velden van de bijbehorende lijst. Als hier velden bijzitten waar meerdere opties kunnen worden gekozen, dan worden deze opties in een array opgesomd.

Voorbeeld member object

{
    "member": {
        "member_id": "9978ydioiZ",
        "list_id": "BaImMu3JZA",
        "email": "maartje@example.net",
        "state": "active",
        "signup_date": "2012-08-13 16:13:07",
        "modified": "2012-08-13 16:14:27",
        "ip": "198.51.100.10",
	"source_url": "http://example.com",
        "custom_fields": {
            "name": "Maartje de Vries",
            "dateofbirth": "1973-05-10 00:00:00",
            "children": 2,
            "prefs": [
                "optionA", 
                "optionB"
            ]
        }
    }
}

Relatie toevoegen

Parameters

list_id (verplicht):	Het id van de lijst waaraan de relatie moet worden toegevoegd
ip (verplicht):	Het IP-adres vanwaar de relatie is aangemeld
email (verplicht):	Het e-mailadres van de toe te voegen relatie
source_url:	De URL vanwaar de relatie is aangemeld
custom_fields:	De waardes van de extra aangemaakte velden. De naam (de key) van het veld moet de 'custom_name' zijn (onderdeel van het Field object). Dit is gelijk aan de 'Relatievariabele' in de applicatie.
options:	Extra aanwijzingen, mogelijkheden zijn: `upsert: true` om velden te overschrijven als het e-mailadres al aan een actieve relatie van deze lijst gekoppeld is. Normaal gesproken zou je een foutmelding krijgen als het e-mailadres al gekoppeld is aan een actieve relatie. Let op: Als een relatie uitgeschreven is en je doet een upsert met dat e-mailadres, dan wordt deze weer op actief gezet. Indien je wilt voorkomen dat een uitgeschreven relatie weer actief wordt, kun je de optie `suppress_reactivation` gebruiken. `suppress_reactivation: true` om te voorkomen dat een uitgeschreven relatie weer op actief wordt gezet bij een upsert `suppress_email_notification: true` om te voorkomen dat bij elke aanmelding via een api een notificatiemailtje wordt verstuurd `ignore_doubleoptin: true` om relaties bij een double-optin lijst meteen actief te maken en ervoor te zorgen dat er geen bevestigingsmail wordt verstuurd bij een aanmelding via de api

Als het een double-optin lijst betreft dan wordt bij elke aanmelding een bevestigingsmail verstuurd, tenzij de optie 'ignore_doubleoptin' wordt meegegeven (zie hierboven).

Als er custom_fields zijn die verplicht zijn gesteld, is het vullen van deze velden via de API ook verplicht.

Definitie

POST https://api.laposta.nl/v2/member

Voorbeeld aanvraag

$ curl https://api.laposta.nl/v2/member \
  -u JdMtbsMq2jqJdQZD9AHC: \
  -d list_id=BaImMu3JZA  \
  -d ip=198.51.100.0  \
  -d email=maartje@example.net \
  -d source_url=http://example.com \
  -d 'custom_fields[name]=Maartje de Vries' \
  -d custom_fields[dateofbirth]=1973-05-10 \
  -d custom_fields[children]=2 \
  -d custom_fields[prefs][]=optionA  \
  -d custom_fields[prefs][]=optionB

Meerkeuze custom fields kunnen gevuld worden met de op dat moment voor dat veld gedefinieerde opties. U kunt dus gewoon de waarde van het veld meegeven. Als er meerdere keuzes gemaakt kunnen worden, dan kunt u deze in een array meegeven; zie het voorbeeld hierboven.

Voorbeeld antwoord

{
    "member": {
        "member_id": "9978ydioiZ",
        "list_id": "BaImMu3JZA",
        "email": "maartje@example.net",
        "state": "active",
        "signup_date": "2012-08-13 16:13:07",
        "ip": "198.51.100.10",
	"source_url": "http://example.com",
        "custom_fields": {
            "name": "Maartje de Vries",
            "dateofbirth": "1973-05-10 00:00:00",
            "children": 2,
            "prefs": [
                "optionA", 
                "optionB"
            ]
        }
    }
}

Relatie opvragen

Alle informatie over een relatie in een member object.

Parameters

list_id (verplicht):	Het id van de lijst waarin de relatie voorkomt
member_id (verplicht):	Het id OF het emailadres van de relatie

Definitie

GET https://api.laposta.nl/v2/member/{member_id}?list_id={list_id}

Voorbeeld aanvraag

$ curl https://api.laposta.nl/v2/member/Du83Hyjhj8?list_id=BaImMu3JZA \ -u JdMtbsMq2jqJdQZD9AHC:

U kunt hier in plaats van het member_id ook het e-mailadres gebruiken. Let op: een '+' in het adres moet weergegeven worden als: %252B

Voorbeeld antwoord

{
    "member": {
        "member_id": "9978ydioiZ",
        "list_id": "BaImMu3JZA",
        "email": "maartje@example.net",
        "state": "active",
        "signup_date": "2012-08-13 16:13:07",
        "ip": "198.51.100.10",
	"source_url": "http://example.com",
        "custom_fields": {
            "name": "Maartje de Vries - Abbink",
            "dateofbirth": "1973-05-10 00:00:00",
            "children": 3,
            "prefs": [
                "optionA", 
                "optionB"
            ]
        }
    }
}

Relatie wijzigen

Parameters

list_id (verplicht):	Het id van de lijst waaraan de relatie moet worden gewijzigd
email:	Het e-mailadres van de te wijzigen relatie
state:	De nieuwe status van de relatie: active of unsubscribed
custom_fields:	De waardes van de extra aangemaakte velden

Definitie

POST https://api.laposta.nl/v2/member/{member_id}

Voorbeeld aanvraag

Dit voorbeeld wijzigt de naam en het aantal kinderen.

$ curl https://api.laposta.nl/v2/member/9978ydioiZ \
  -u JdMtbsMq2jqJdQZD9AHC: \
  -d list_id=BaImMu3JZA  \
  -d 'custom_fields[name]=Maartje de Vries - Abbink' \
  -d custom_fields[children]=3

U kunt hier in plaats van het member_id ook het e-mailadres gebruiken.

Meerkeuze custom fields die niet verplicht zijn kunnen leeggemaakt worden door de variabele wel op te nemen in de aanvraag voor de wijziging, maar zonder waarde.

Voorbeeld antwoord

{
    "member": {
        "member_id": "9978ydioiZ",
        "list_id": "BaImMu3JZA",
        "email": "maartje@example.net",
        "state": "active",
        "signup_date": "2012-08-13 16:13:07",
        "ip": "198.51.100.10",
	"source_url": "http://example.com",
        "custom_fields": {
            "name": "Maartje de Vries - Abbink",
            "dateofbirth": "1973-05-10 00:00:00",
            "children": 3,
            "prefs": [
                "optionA", 
                "optionB"
            ]
        }
    }
}

Relatie verwijderen

Hiermee verwijdert u een relatie definitief. Als de relatie niet bestaat wordt een foutmelding gegeven. Als antwoord krijgt u weer een member object, maar nu met state 'deleted'. Hierna is deze relatie niet nogmaals op te vragen.

Parameters

list_id (verplicht):	Het id van de lijst waarin de relatie voorkomt
member_id (verplicht):	Het id OF het emailadres van de relatie

Definitie

DELETE https://api.laposta.nl/v2/member/{member_id}

Voorbeeld aanvraag

$ curl https://api.laposta.nl/v2/member/9978ydioiZ?list_id=BaImMu3JZA \
  -u JdMtbsMq2jqJdQZD9AHC: \
  -X DELETE

U kunt hier in plaats van het member_id ook het e-mailadres gebruiken.

Voorbeeld antwoord

{
    "member": {
        "member_id": "9978ydioiZ",
        "list_id": "BaImMu3JZA",
        "email": "maartje@example.net",
        "state": "deleted",
        "signup_date": "2012-08-13 16:13:07",
        "ip": "198.51.100.10",
	"source_url": "http://example.com",
        "custom_fields": {
            "name": "Maartje de Vries - Abbink",
            "dateofbirth": "1973-05-10 00:00:00",
            "children": 3,
            "prefs": [
                "optionA", 
                "optionB"
            ]
        }
    }
}

Alle relaties van een lijst opvragen

Alle relaties in een array van member objecten. De member objecten zijn opgenomen in een array met de naam 'data'.

Parameters

list_id (verplicht):	Het id van de lijst waaraan de relaties opgevraagd worden
state:	De status van de opgevraagde relaties: active, unsubscribed of cleaned

Definitie

GET https://api.laposta.nl/v2/member

Voorbeeld aanvraag

$ curl 'https://api.laposta.nl/v2/member?list_id=BaImMu3JZA&state=active' \
  -u JdMtbsMq2jqJdQZD9AHC:

Voorbeeld antwoord

{
    "data": [
        {
            "member": {
                "member_id": "9978ydioiZ",
                "list_id": "BaImMu3JZA",
                "email": "maartje@example.net",
                "state": "active",
                "signup_date": "2012-08-13 16:13:07",
                "ip": "198.51.100.10",
		"source_url": "http://example.com",
                "custom_fields": {
                    "name": "Maartje de Vries - Abbink",
                    "dateofbirth": "1973-05-10 00:00:00",
                    "children": 3,
                    "prefs": [
                        "optionA", 
                        "optionB"
                    ]
                }
            }
	},
        {
            "member": {
                "member_id": "Hy8RA178HB",
                "list_id": "BaImMu3JZA",
                "email": "stefan@example.net",
                "state": "active",
                "signup_date": "2012-06-24 11:54:12",
                "ip": "198.51.100.10",
		"source_url": "http://example.com",
                "custom_fields": {
                    "name": "Stefan van Aalst",
                    "dateofbirth": null,
                    "children": 0,
                    "prefs": [
                        "optionA"
                    ]
                }
            }
	}
    ]
}

Webhooks

Webhooks vormen een apart onderdeel van de API. Bij de normale API gaat het opvragen van informatie steeds van de ontwikkelaar uit. Bij webhooks is het andersom, en neem Laposta het initiatief om de ontwikkelaar van iets op de hoogte te stellen. Een webhook doet dat door het aanroepen van een URL die door u is opgegeven; in de vorm van een POST met een JSON object met informatie.

U kunt URL's opgeven voor het toevoegen, wijzigen of verwijderen van relaties. Stel dat u een webhook aanmaakt voor toevoegingen, en iemand meld zich aan via een aanmeldformulier van Laposta, dan krijgt u vrijwel meteen na deze nieuwe aanmelding een POST op de door u opgegeven URL.

Toepassing: synchronisatie met andere systemen

Onze API wordt het meest gebruikt om het relatiebestand in Laposta te synchroniseren met een andere applicatie, bijvoorbeeld een CMS of een CRM. Het toevoegen aan en wijzigen van relaties aan Laposta wordt dan via de API gedaan (zoals hierboven beschreven). Webhooks stellen uw applicatie op de hoogte van veranderingen in het relatiebestand die binnen Laposta plaats vinden (aan- of afmeldingen, of wijzigingen). Met de combinatie van deze twee functies kunt u de twee bestanden synchroon houden.

Het verwerken van webhooks

Bij een webhook wordt er een URL aangeroepen op uw server. De meegegeven json data staat in de body van de aanvraag. U bent helemaal vrij in de manier waarop de informatie verwerkt wordt. Om aan te geven dat u een webhook correct ontvangen hebt, moet de server een 200 HTTP statuscode teruggeven. (Dit zal meestal standaard het geval zijn).

Na bewerkingen via de API

Standaard worden de webhooks niet aangeroepen als u relaties toevoegt of wijzigt via de API. De gedachte hierbij is dat u al op de hoogte bent van de wijzigingen, en het ontvangen van deze informatie via een webhook dubbelop zou zijn. Het kan echter voorkomen dat dit toch gewenst is (bijvoorbeeld als de API wordt aangeroepen vanuit een extern formulier). Dat is mogelijk; als u ons hierover een mailtje stuurt dan kunnen we dit activeren.

Webhooks registreren

U kunt webhooks per lijst registreren. Dit doet u door naar de betreffende lijst te gaan (onder Relaties), en dan naar Kenmerken lijst. Daar vindt u het tabblad Webhooks.

Voor elke webhook kunt u aangeven voor welke event deze moet worden aangeroepen: het toevoegen van een relatie, het wijzigen van een relatie, of het verwijderen van een relatie. Daarbij geeft u de URL op waarnaar de informatie gePOST moet worden.

Het is ook mogelijk de webhooks via deze API te beheren; zie daarvoor de informatie hieronder.

Timing

Het kan zijn dat het aanroepen van een webhook niet lukt, bijvoorbeeld omdat uw server niet bereikbaar is of een foutmelding geeft. Laposta blijft de webhook dan nog een aantal keer (7 om precies te zijn) aanbieden. Eerst na 5 minuten, en dan in oplopende intervallen tot ongeveer 14 dagen. Als er dan nog geen contact mogelijk wordt de webhook verwijderd.

Bundeling events

Elke 5 seconden worden de op dat moment aanwezige webhooks aangeroepen. Als het er meerdere zijn, dan worden ze gebundeld, tot maximaal 1000 events per aanvraag. Zo wordt voorkomen dat uw server overspoeld wordt met aanvragen, bijvoorbeeld bij het importeren van grotere hoeveelheden relaties in Laposta.

Opbouw webhook

Op de door u opgegeven URL ontvangt u een object in JSON formaat. Dit object bestaat uit een array met de naam data, waarin de verschillende events worden opgenomen. Er kunnen dus meerdere events in een enkele aanvraag zijn opgenomen (zie hierboven onder 'Bundeling events').

Velden

type:	Het type webhook (steeds member)
event:	De reden waarom de webhook is aangeroepen. Kan zijn: subscribed, modified of deactivated
data:	De gegevens van het object dat toegevoegd, gewijzigd of verwijderd is. In dit geval een member object.
info:	Extra informatie over de aanroep van de webhook, zie hieronder
date_requested:	Het moment waarop deze aanvraag is verzonden

Velden info object

date_event:

Het moment waarop dit event plaatshad (en de webhook getriggerd werd)

action (optioneel):

Extra informatie over het event, verschillende opties bij de diverse events. Bij event subscribed:

subscribed:	Relatie toegevoegd
rebsubscribed:	Relatie opnieuw toegevoegd

Bij event deactivated:

unsubscribed:	Relatie is afgemeld
deleted:	Relatie verwijderd
hardbounce:	Relatie opgeschoond na hard bounce

source (optioneel):

Bron van het event: kan zij app (binnen de webinterface) of external (via bijvoorbeeld een aanmeldformulier)

Voorbeeld webhook response

{
    "data": [
        {
            "type": "member",
            "event": "deactivated",
            "data": {
                "member_id": "9978ydioiZ",
                "list_id": "BaImMu3JZA",
                "email": "maartje@example.net",
                "state": "deleted",
                "signup_date": "2012-08-13 16:13:07",
                "ip": "198.51.100.10",
		"source_url": "http://example.com",
                "custom_fields": {
                    "name": "Maartje de Vries - Abbink",
                    "dateofbirth": "1973-05-10 00:00:00",
                    "children": 3,
                    "prefs": [
                        "optionA", 
                        "optionB"
                    ]
                }
            },
            "info": { 
                "source": "app",
                "action": "deleted", 
                "date_event": "2012-08-17 20:56:31
            }
        }
    ],
    "date_requested": "2012-08-17 20:56:34
}

Webhooks beheren

U kunt de webhooks ook met de API beheren. Hieronder staat uitgelegd hoe u webhooks kunt opvragen, toevoegen en wijzigen.

URL patronen

/v2/webhook
/v2/webhook/{webhook_id}

Het webhook object

Velden

webhook_id:	Het id van deze webhook
list_id:	Het id van de lijst waartoe het veld behoort
created:	Moment van aanmaken
modified:	Moment van laatste wijziging
state:	De status van deze webhook: `active` of `deleted`
event:	Wanneer wordt de webhook aangeroepen? (`subscribed`, `modified` of `deactivated`)
url:	De aan te roepen url
blocked:	Is het aanroepen van de webhook (tijdelijk) geblokkeerd? (`true` of `false`)

Voorbeeld webhook object

{
    "webhook": {
        "webhook_id": "cW5ls8IVJl",
        "list_id": "BaImMu3JZA",
        "created": "2012-10-31 17:03:21",
        "modified": "2012-10-31 17:12:08",
	"state": "active",
        "event": "subscribed",
        "url": "http://example.net/webhook.asp",
        "blocked": false
    }
}

Webhook toevoegen

Als er iets niet klopt aan de meegegeven parameters dan wordt bij de foutmelding een code en een melding weergegeven. Zie hierboven bij Foutmeldingen wat de codes betekenen.

Parameters

list_id (verplicht):	Het id van de lijst waartoe het veld behoort
event (verplicht):	Wanneer wordt de webhook aangeroepen? (`subscribed`, `modified` of `deactivated`)
url (verplicht):	De aan te roepen url
blocked (verplicht):	Is het aanroepen van de webhook (tijdelijk) geblokkeerd? (`true` of `false`)

Definitie

POST https://api.laposta.nl/v2/webhook

Voorbeeld aanvraag

$ curl https://api.laposta.nl/v2/webhook \
  -u JdMtbsMq2jqJdQZD9AHC: \
  -d list_id=BaImMu3JZA \
  -d event=modified \
  -d url=http://example.com/webhook.pl \
  -d blocked=false

Voorbeeld antwoord

{
    "webhook": {
        "webhook_id": "JH_y9dEsfH",
        "list_id": "BaImMu3JZA",
        "created": "2012-10-31 21:08:58",
        "modified": null,
        "state": "active",
        "event": "modified",
        "url": "http://example.com/webhook.pl",
        "blocked": false
    }
}

Webhook opvragen

Alle informatie over een webhook.

Parameters

list_id (verplicht):	Het id van de lijst waarbij het veld hoort
webhook_id(verplicht):	Het id van het op te vragen veld

Definitie

GET https://api.laposta.nl/v2/webhook/{webhook_id}

Voorbeeld aanvraag

$ curl https://api.laposta.nl/v2/webhook/cW5ls8IVJl?list_id=BaImMu3JZA \
  -u JdMtbsMq2jqJdQZD9AHC:

Voorbeeld antwoord
{
    "webhook": {
        "webhook_id": "cW5ls8IVJl",
        "list_id": "BaImMu3JZA",
        "created": "2012-10-31 17:03:21",
        "modified": "2012-10-31 17:12:08",
        "state": "active",
        "event": "subscribed",
        "url": "http://example.net/webhook.asp",
        "blocked": false
    }
}

Webhook wijzigen

U hoeft alleen de velden die gewijzigd moeten worden in de aanvraag mee te sturen. Velden die niet worden genoemd houden hun huidige waarde. Zodra een veld wordt genoemd wordt het wel gecontroleerd, en kan dus voor een foutmelding zorgen. Bij deze foutmelding wordt een code weergegeven met een melding. Zie hierboven bij Foutmeldingen wat de codes betekenen.

Parameters

list_id (verplicht):	Het id van de lijst waartoe het veld behoort
webhook_id(verplicht):	Het id van het op te vragen veld
event:	Wanneer wordt de webhook aangeroepen? (`subscribed`, `modified` of `deactivated`)
url:	De aan te roepen url
blocked:	Is het aanroepen van de webhook (tijdelijk) geblokkeerd? (`true` of `false`)

Definitie

POST https://api.laposta.nl/v2/webhook/{webhook_id}

Voorbeeld aanvraag

Dit voorbeeld wijzigt de url.

$ curl https://api.laposta.nl/v2/webhook/JH_y9dEsfH \
  -u JdMtbsMq2jqJdQZD9AHC: \
  -d list_id=BaImMu3JZA \
  -d url=http://example.com/dir/webhook.pl

Voorbeeld antwoord

{
    "webhook": {
        "webhook_id": "iH52rJwguo",
        "list_id": "BaImMu3JZA",
        "created": "2012-10-31 21:08:58",
        "modified": "2012-10-31 21:32:21",
        "state": "active",
        "event": "modified",
        "url": "http://example.com/dir/webhook.pl",
        "blocked": false
    }
}

Webhook verwijderen

Hiermee verwijdert u een webhook definitief. Eventuele uitstaande aanvragen van de webhook worden nog wel afgerond. Als een veld niet bestaat wordt een foutmelding gegeven. Als antwoord krijgt u weer een webhook object, maar nu met state 'deleted'. Hierna is de webhook niet nogmaals op te vragen.

Parameters

webhook_id (verplicht):	Het id van de te verwijderen webhook
list_id (verplicht):	Het id van de lijst waartoe de webhook behoort

Definitie

DELETE https://api.laposta.nl/v2/webhook/{webhook_id}

Voorbeeld aanvraag

$ curl https://api.laposta.nl/v2/webhook/8HdlEGtlml?list_id=BaImMu3JZA \
  -u JdMtbsMq2jqJdQZD9AHC: \
  -X DELETE

Voorbeeld antwoord

{
    "webhook": {
        "webhook_id": "8HdlEGtlml",
        "list_id": "BaImMu3JZA",
        "created": "2012-10-31 17:11:15",
        "modified": null,
        "state": "deleted",
        "event": "modified",
        "url": "http://example.com/laposta.php",
        "blocked": true
    }
}

Alle webhooks van een lijst opvragen

Alle webhooks van een lijst in een array van webhook objecten. De webhook objecten zijn opgenomen in een array met de naam 'data'.

Parameters

list_id (verplicht):

Het id van de lijst waarbij de webhooks horen

Definitie

GET https://api.laposta.nl/v2/webhook

Voorbeeld aanvraag

$ curl https://api.laposta.nl/v2/webhook?list_id=BaImMu3JZA \
  -u JdMtbsMq2jqJdQZD9AHC:

Voorbeeld antwoord

{
    "data": [
	{
	    "webhook": {
		"webhook_id": "8HdlEGtlml",
		"list_id": "BaImMu3JZA",
		"created": "2012-10-31 17:11:15",
		"modified": null,
		"state": "active",
		"event": "modified",
		"url": "http://example.com/laposta.php",
		"blocked": false
	    }
	},
	{
	    "webhook": {
		"webhook_id": "mh7Qao0_lR",
		"list_id": "BaImMu3JZA",
		"created": "2012-09-20 14:20:14",
		"modified": null,
		"state": "active",
		"event": "subscibed",
		"url": "http://example.com/laposta.php",
		"blocked": false
	    }
	}
    ]
}

Campagnes

Campagnes opvragen, aanmaken, vullen en versturen.

URL patronen

/v2/campaign
/v2/campaign/{campaign_id}
/v2/campaign/{campaign_id}/content
/v2/campaign/{campaign_id}/action/send
/v2/campaign/{campaign_id}/action/schedule

Het object

Velden

account_id:	Het id van dit account
campaign_id:	Het id van de campagne
created:	Moment van aanmaken
modified:	Moment van laatste wijziging
type:	Het soort campagne (op dit moment alleen `regular`)
delivery_requested:	Wanneer verzenden?
delivery_started:	Start laatste keer verzenden
delivery_ended:	Einde laatste keer verzenden
name:	Interne naam campagne
subject:	Onderwerpregel
from:	Afzender (naam en e-mailadres)
reply_to:	E-mailadres voor reacties
list_ids:	Gekoppelde lijsten en segementen
stats:	Gekoppelde webstatistieken
web:	Url naar webversie
screenshot:	Screenshots van campagne

Voorbeeld campaign object

{
    "campaign": {
        "account_id": "wFiUS4HL4e",
        "campaign_id": "njhgaf61ye",
        "created": "2014-12-11 11:26:19",
        "modified": "2014-12-11 11:27:31",
        "type": "regular",
        "delivery_requested": null,
        "delivery_started": "2014-12-11 11:27:29",
        "delivery_ended": "2014-12-11 11:27:31",
        "name": "Mijn eerste campagne",
        "subject": "Mijn eerste campagne",
        "from": {
            "name": "Laposta API",
            "email": "api@laposta.nl"
        },
        "reply_to": "api@laposta.nl",
	"list_ids": {
            "kxhysrt26s": [
                "2noVadDLbd"
            ],
            "t1jmacge9a": [
                "GJn80BiYxo"
            ],
            "shb5vujyxj": [],
            "eiwhvx595g": [
                "PtIXMx2sG0"
            ]
        },
	"stats": {
	    "ga": "true",
	    "mtrack": "false"
	},
        "web": "https://laposta-api.email-provider.nl/web/wFiUS4HL4e/njhgaf61ye",
        "screenshot": {
            "113x134": "https://app.laposta.nl/clients/images/screenshots/9dknAdbAXm.2.png"
            "226x268": "https://app.laposta.nl/clients/images/screenshots/9dknAdbAXm.2.png"
        }
    }
}

Campagne aanmaken

Parameters

type (verplicht):	Type campagne (moet zijn: `regular`)
name (verplicht):	Een naam voor deze campagne, voor intern gebruik
subject (verplicht):	De onderwerpregel
from[name] (verplicht):	De naam van de afzender
from[email] (verplicht):	Het e-mailadres van de afzender (dit moet een binnen het programma goedgekeurd afzendadres zijn)
reply_to:	Het e-mailadres bij beantwoorden
list_ids (verplicht):	Ontvangers, array van list_id's en eventuele segment_id's
stats[ga]:	Koppel Google Analytics (`true` of `false`)
stats[mtrack]:	Koppel Mtrack (`true` of `false`)

De campagne is na de aanvraag nog niet gevuld of ingepland. Gebruik hiervoor de /content en /action patronen, zie hieronder.

Definitie

POST https://api.laposta.nl/v2/campaign

Voorbeeld aanvraag

$ curl https://api.laposta.nl/v2/campaign \
  -u JdMtbsMq2jqJdQZD9AHC: \
  -d type=regular \
  -d 'name=Test via API' \
  -d 'subject=Hello from us' \
  -d 'from[name]=Max de Vries' \
  -d from[email]=max@example.net \
  -d reply_to=reply@example.net \
  -d list_ids[]=nnhnkrytua \
  -d list_ids[]=srbhotdwob \
  -d stats[ga]=true

Voorbeeld antwoord

{
    "campaign": {
        "account_id": "wFiUS4HL4e",
        "campaign_id": "pbrqulw2tc",
        "created": "2016-05-16 21:24:12",
        "modified": null,
        "type": "regular",
        "delivery_requested": null,
        "delivery_started": null,
        "delivery_ended": null,
        "name": "Test via API",
        "subject": "Hello from us",
        "from": {
            "name": "Max de Vries",
            "email": "max@example.net"
        },
        "reply_to": "reply@example.net",
	"list_ids": {
            "kxhysrt26s": [
                "2noVadDLbd"
            ],
            "t1jmacge9a": [
                "GJn80BiYxo"
            ],
            "shb5vujyxj": [],
            "eiwhvx595g": [
                "PtIXMx2sG0"
            ]
        },
        "stats": {
            "ga": "true",
            "mtrack": "false"
        },
        "web": "https://laposta-api.email-provider.nl/web/wFiUS4HL4e/pbrqulw2tc",
        "screenshot": {
            "113x134": "https://app.laposta.nl/clients/images/screenshots/default/113x134_nl.png",
            "226x268": "https://app.laposta.nl/clients/images/screenshots/default/113x134_nl.png"
        }
    }
}

Campagne opvragen

Alle informatie over een campagne.

Parameters

campaign_id (verplicht):

Het id van de campagne

Definitie

GET https://api.laposta.nl/v2/campaign/{campaign_id}

Voorbeeld aanvraag

$ curl https://api.laposta.nl/v2/campaign/njhgaf61ye \
  -u JdMtbsMq2jqJdQZD9AHC:

Voorbeeld antwoord
{
    "campaign": {
        "account_id": "wFiUS4HL4e",
        "campaign_id": "njhgaf61ye",
        "created": "2014-12-11 11:26:19",
        "modified": "2014-12-11 11:27:31",
        "type": "regular",
        "delivery_requested": null,
        "delivery_started": "2014-12-11 11:27:29",
        "delivery_ended": "2014-12-11 11:27:31",
        "name": "Mijn eerste campagne",
        "subject": "Mijn eerste campagne",
        "from": {
            "name": "Laposta API",
            "email": "api@laposta.nl"
        },
        "reply_to": "api@laposta.nl",
	"list_ids": {
            "kxhysrt26s": [
                "2noVadDLbd"
            ],
            "t1jmacge9a": [
                "GJn80BiYxo"
            ],
            "shb5vujyxj": [],
            "eiwhvx595g": [
                "PtIXMx2sG0"
            ]
        },
	"stats": {
	    "ga": "true",
	    "mtrack": "false"
	},
        "web": "https://laposta-api.email-provider.nl/web/wFiUS4HL4e/njhgaf61ye",
        "screenshot": {
            "113x134": "https://app.laposta.nl/clients/images/screenshots/9dknAdbAXm.2.png"
        }
    }
}

Campagne wijzigen

U hoeft alleen de velden die gewijzigd moeten worden in de aanvraag mee te sturen. Velden die niet worden genoemd houden hun huidige waarde. Zodra een veld wordt genoemd wordt het wel gecontroleerd, en kan dus voor een foutmelding zorgen. Bij deze foutmelding wordt een code weergegeven met een melding. Zie hierboven bij Foutmeldingen wat de codes betekenen.

Parameters

campaign_id (verplicht):	Het id van de campagne die gewijzigd moet worden
name:	Een naam voor deze campagne, voor intern gebruik
subject:	De onderwerpregel
from[name]:	De naam van de afzender
from[email]:	Het e-mailadres van de afzender (dit moet een binnen het programma goedgekeurd afzendadres zijn)
reply_to:	Het e-mailadres bij beantwoorden
list_ids:	Ontvangers, array van list_id's en eventuele segment_ids
stats[ga]:	Koppel Google Analytics (`true` of `false`)
stats[mtrack]:	Koppel Mtrack (`true` of `false`)

Definitie

POST https://api.laposta.nl/v2/campaign/{campaign_id}

Voorbeeld aanvraag

Dit voorbeeld wijzigt de onderwerpregel.

$ curl https://api.laposta.nl/v2/campaign/pbrqulw2tc \
  -u JdMtbsMq2jqJdQZD9AHC: \
  -d 'subject=Hello from us, modified'

Voorbeeld antwoord

{
    "campaign": {
        "account_id": "wFiUS4HL4e",
        "campaign_id": "pbrqulw2tc",
        "created": "2016-05-16 21:24:12",
        "modified": "2016-05-16 21:51:27",
        "type": "regular",
        "delivery_requested": null,
        "delivery_started": null,
        "delivery_ended": null,
        "name": "Test via API",
        "subject": "Hello from us, modified",
        "from": {
            "name": "Max de Vries",
            "email": "max@example.net"
        },
        "reply_to": "reply@example.net",
	"list_ids": {
            "kxhysrt26s": [
                "2noVadDLbd"
            ],
            "t1jmacge9a": [
                "GJn80BiYxo"
            ],
            "shb5vujyxj": [],
            "eiwhvx595g": [
                "PtIXMx2sG0"
            ]
        },
        "stats": {
            "ga": "true",
            "mtrack": "false"
        },
        "web": "https://laposta-api.email-provider.nl/web/wFiUS4HL4e/pbrqulw2tc",
        "screenshot": {
            "113x134": "https://app.laposta.nl/clients/images/screenshots/default/113x134_nl.png",
            "226x268": "https://app.laposta.nl/clients/images/screenshots/default/113x134_nl.png"
        }
    }
}

Campagne verwijderen

Hiermee verwijdert u een campagne. Campagnes die nog niet verzonden zijn worden definitief verwijderd. Campagnes die verzonden zijn worden pas na 180 dagen definitief verwijderd. In de tussentijd zijn ze te herstellen in het overzicht van campagnes in ons programma.

Als antwoord krijgt u het campaign object, maar nu met state 'deleted'. Hierna is de campagne niet nogmaals op te vragen.

Parameters

campaign_id (verplicht):

Het id van de te verwijderen campagne

Definitie

DELETE https://api.laposta.nl/v2/campaign/{campaign_id}

Voorbeeld aanvraag

$ curl https://api.laposta.nl/v2/campaign/az0ndh7akc \
  -u JdMtbsMq2jqJdQZD9AHC: \
  -X DELETE

Voorbeeld antwoord

{
    "campaign": {
        "account_id": "wFiUS4HL4e",
        "campaign_id": "az0ndh7akc",
        "created": "2016-05-16 22:44:49",
        "modified": "2016-05-16 22:44:49",
        "type": "regular",
        "delivery_requested": null,
        "delivery_started": null,
        "delivery_ended": null,
        "name": "Test API 16-05-2016 22:44:49",
        "subject": "This is the subject",
        "from": {
            "name": "Max de Vries",
            "email": "max@example.net"
        },
        "reply_to": "reply@example.net",
	"list_ids": {
            "kxhysrt26s": [
                "2noVadDLbd"
            ],
            "t1jmacge9a": [
                "GJn80BiYxo"
            ],
            "shb5vujyxj": [],
            "eiwhvx595g": [
                "PtIXMx2sG0"
            ]
        },
        "stats": {
            "ga": "true",
            "mtrack": "false"
        },
        "web": "https://laposta-api.email-provider.nl/web/wFiUS4HL4e/az0ndh7akc",
        "screenshot": {
            "113x134": "https://app.laposta.nl/clients/images/screenshots/default/113x134_nl.png",
            "226x268": "https://app.laposta.nl/clients/images/screenshots/default/113x134_nl.png"
        },
        "state": "deleted"
    }
}

Alle campagnes van een account opvragen

Alle campagnes in een array van campaign objecten. De campaign objecten zijn opgenomen in een array met de naam 'data'.

Parameters

Geen.

Definitie

GET https://api.laposta.nl/v2/campaign

Voorbeeld aanvraag

$ curl https://api.laposta.nl/v2/campaign \
  -u JdMtbsMq2jqJdQZD9AHC:

Voorbeeld antwoord

{
    "data": [
        {
            "campaign": {
                "account_id": "wFiUS4HL4e",
                "campaign_id": "njhgaf61ye",
                "created": "2014-12-11 11:26:19",
                "modified": "2014-12-11 11:27:31",
		"type": "regular",
		"delivery_requested": null,
                "delivery_started": "2014-12-11 11:27:29",
                "delivery_ended": "2014-12-11 11:27:31",
                "name": "Mijn eerste campagne",
                "subject": "Mijn eerste campagne",
                "from": {
                    "name": "Laposta API",
                    "email": "api@laposta.nl"
                },
                "reply_to": "api@laposta.nl",
		"list_ids": {
		    "kxhysrt26s": [
			"2noVadDLbd"
		    ],
		    "t1jmacge9a": [
			"GJn80BiYxo"
		    ],
		    "shb5vujyxj": [],
		    "eiwhvx595g": [
			"PtIXMx2sG0"
		    ]
		},
		"stats": {
		    "ga": "true",
		    "mtrack": "false"
		},
                "web": "https://laposta-api.email-provider.nl/web/wFiUS4HL4e/njhgaf61ye",
                "screenshot": {
                    "113x134": "https://app.laposta.nl/clients/images/screenshots/9dknAdbAXm.2.png"
                }
            }
        },
        {
            "campaign": {
                "account_id": "wFiUS4HL4e",
                "campaign_id": "qzgllqculd",
                "created": "2014-12-11 11:27:45",
                "modified": "2014-12-11 11:27:56",
		"type": "regular",
		"delivery_requested": null,
                "delivery_started": null,
                "delivery_ended": null,
                "name": "Mijn tweede campagne",
                "subject": "Mijn tweede campagne",
                "from": {
                    "name": "Laposta API",
                    "email": "api@laposta.nl"
                },
                "reply_to": "api@laposta.nl",
		"list_ids": {
		    "kxhysrt26s": [
			"2noVadDLbd"
		    ],
		    "t1jmacge9a": [
			"GJn80BiYxo"
		    ],
		    "shb5vujyxj": [],
		    "eiwhvx595g": [
			"PtIXMx2sG0"
		    ]
		},
		"stats": {
		    "ga": "true",
		    "mtrack": "false"
		},
                "web": "https://laposta-api.email-provider.nl/web/wFiUS4HL4e/qzgllqculd",
                "screenshot": {
                    "113x134": "https://app.laposta.nl/clients/images/screenshots/ClCvez9GXQ.2.png"
                }
            }
        }
    ]
}

Campagne content opvragen

De inhoud van een campagne opvragen.

Let op: dit kan alleen als het een campagne betreft die geïmporteerd is, en niet bij een campagne die binnen de applicatie is gemaakt met de drag & drop-editor.

Parameters

campaign_id (verplicht):

Het id van de campagne

Definitie

GET https://api.laposta.nl/v2/campaign/{campaign_id}/content

Voorbeeld aanvraag

$ curl https://api.laposta.nl/v2/campaign/njhgaf61ye/content \
  -u JdMtbsMq2jqJdQZD9AHC:

Voorbeeld antwoord
{
    "campaign": {
        "account_id": "wFiUS4HL4e",
        "campaign_id": "pbrqulw2tc",
        "plaintext": "Bekijk hier de webversie:\n/tag/web\n\n           \n\n \t\tZet hier een korte, pakkende omschrijving van uw nieuwsbrief.\n\n \t\tBekijk de webversie [1]\n\n \t\tDe titel van dit blok\n\n Dit is het blok Tekst. Als u deze tekst aanklikt, kunt u deze\nwijzigen. Aan de linkerkant krijgt u twee tabs te zien. Onder de tab\nInhoud kunt u uw tekst invoeren en iets opmaken. Hier kunt u ook de\ntitel van dit blok aanpassen. Onder de tab Vormgeving doet u de grote\nopmaak, van de titel, de tekst en het vak.\n\nWilt u weer naar het overzicht van blokken en de opties voor algehele\nopmaak? Sla dan uw blok op of klik op de buitenkant van uw\nnieuwsbrief. \n\n Deze e-mail is verstuurd aan {{email}} [2].\nAls u geen nieuwsbrief meer wilt ontvangen, kunt u zich hier afmelden\n[3].\nU kunt ook uw gegevens inzien en wijzigen [4].\nVoor een goede ontvangst voegt u {{from_email}} [5] toe aan uw\nadresboek. \n\nDeze email is verstuurd aan {{email}}.\nAls u geen nieuwsbrief meer wilt ontvangen, kunt u zich hier afmelden\n[6].\n\n \n\nLinks:\n------\n[1] http://clients.laposta.nl/tag/web\n[2] mailto:{{email}}\n[3] http://clients.laposta.nl/tag/unsubscribe\n[4] http://clients.laposta.nl/tag/edit\n[5] mailto:{{from_email}}\n[6] /tag/unsubscribe\n",
        "html": "<!DOCTYPE html PUBLIC \"-//W3C//DTD XHTML 1.0 Transitional //EN\" \"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd\">\n<html xmlns=\"http://www.w3.org/1999/xhtml\" xmlns:v=\"urn:schemas-microsoft-com:vml\" xmlns:o=\"urn:schemas-microsoft-com:office:office\">\n<head>\n<style type=\"text/css\">\n\n</style>\n<meta http-equiv=\"Content-Type\" content=\"text/html; charset=utf-8\" /> ... <table cellspacing=\"0\" cellpadding=\"0\"><tr><td><![endif]-->\n</td></tr></table>\n<table width=\"100%\" cellspacing=\"0\" cellpadding=\"30\" border=\"0\" bgcolor=\"#ffffff\"><tr><td>&nbsp;</td></tr><tr><td align=\"center\" style=\"color:#333333 !important;line-height:17px !important;font-size:13px !important;font-family:arial !important;font-weight:normal !important\">Deze email is verstuurd aan {{email}}.<br>Als u geen nieuwsbrief meer wilt ontvangen, kunt u zich <a style=\"color:#333;text-decoration:underline;font-size:13px;font-family:arial;font-weight:normal\" href=\"/tag/unsubscribe\">hier afmelden</a>.</td></tr></table></body>\n</html>",
	"import_url": "https://example.net/newsletter"
    }
}

Campagne content vullen

De inhoud van een campagne vullen.

Parameters

De campagne kan ofwel direct gevuld worden met html, ofwel via een url, waarbij Laposta de html importeert die op de opgegeven url te vinden is. Een van beide moet gekozen worden. Als beide parameters worden meegegeven dan wordt de html genomen.

campaign_id (verplicht):	Het id van de campagne
html:	De html voor de campagne
import_url:	De url vanwaar de html geïmporteerd moet worden
inline_css:	Eventueel inlinen van css (`true` of `false`)

Rapportage resultaat

Als het importeren niet lukt volgt er een 400-foutmelding van de api. Als het wel lukt om de html te importeren, maar er zijn tijdens de import problemen gevonden, dan worden die in de variabele report in het antwoord getoond. Het kan hier gaan om:

javascript:	Er is javascript aangetroffen
flash:	Er is flash aangetroffen
no_unsubscribe:	Er is geen afmeldlink gevonden
empty_unsubscribe:	Er is een lege afmeldlink gevonden
css:	Er zijn ontbrekende externe css bestanden (worden opgesomd)
images:	Er zijn ontbrekende externe afbeeldingen (worden opgesomd)

Het is voor het versturen niet noodzakelijk deze problemen op te lossen, maar wel geadviseerd.

Reclame en afmeldink

Bij een gratis account wordt aan de onderkant van de nieuwsbrief onze reclame toegevoegd. Als de aangeboden html geen afmeldlink bevat, dan wordt ook deze door ons programma toegevoegd.

Definitie

POST https://api.laposta.nl/v2/campaign/{campaign_id}/content

Voorbeeld aanvraag

curl https://api.laposta.nl/v2/campaign/pbrqulw2tc/content \
  -u JdMtbsMq2jqJdQZD9AHC: \
  -d import_url=https://example.net/newsletter

Voorbeeld antwoord
{
    "campaign": {
        "account_id": "wFiUS4HL4e",
        "campaign_id": "pbrqulw2tc",
        "plaintext": "Bekijk hier de webversie:\n/tag/web\n\n           \n\n \t\tZet hier een korte, pakkende omschrijving van uw nieuwsbrief.\n\n \t\tBekijk de webversie [1]\n\n \t\tDe titel van dit blok\n\n Dit is het blok Tekst. Als u deze tekst aanklikt, kunt u deze\nwijzigen. Aan de linkerkant krijgt u twee tabs te zien. Onder de tab\nInhoud kunt u uw tekst invoeren en iets opmaken. Hier kunt u ook de\ntitel van dit blok aanpassen. Onder de tab Vormgeving doet u de grote\nopmaak, van de titel, de tekst en het vak.\n\nWilt u weer naar het overzicht van blokken en de opties voor algehele\nopmaak? Sla dan uw blok op of klik op de buitenkant van uw\nnieuwsbrief. \n\n Deze e-mail is verstuurd aan {{email}} [2].\nAls u geen nieuwsbrief meer wilt ontvangen, kunt u zich hier afmelden\n[3].\nU kunt ook uw gegevens inzien en wijzigen [4].\nVoor een goede ontvangst voegt u {{from_email}} [5] toe aan uw\nadresboek. \n\nDeze email is verstuurd aan {{email}}.\nAls u geen nieuwsbrief meer wilt ontvangen, kunt u zich hier afmelden\n[6].\n\n \n\nLinks:\n------\n[1] http://clients.laposta.nl/tag/web\n[2] mailto:{{email}}\n[3] http://clients.laposta.nl/tag/unsubscribe\n[4] http://clients.laposta.nl/tag/edit\n[5] mailto:{{from_email}}\n[6] /tag/unsubscribe\n",
        "html": "<!DOCTYPE html PUBLIC \"-//W3C//DTD XHTML 1.0 Transitional //EN\" \"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd\">\n<html xmlns=\"http://www.w3.org/1999/xhtml\" xmlns:v=\"urn:schemas-microsoft-com:vml\" xmlns:o=\"urn:schemas-microsoft-com:office:office\">\n<head>\n<style type=\"text/css\">\n\n</style>\n<meta http-equiv=\"Content-Type\" content=\"text/html; charset=utf-8\" /> ... <table cellspacing=\"0\" cellpadding=\"0\"><tr><td><![endif]-->\n</td></tr></table>\n<table width=\"100%\" cellspacing=\"0\" cellpadding=\"30\" border=\"0\" bgcolor=\"#ffffff\"><tr><td>&nbsp;</td></tr><tr><td align=\"center\" style=\"color:#333333 !important;line-height:17px !important;font-size:13px !important;font-family:arial !important;font-weight:normal !important\">Deze email is verstuurd aan {{email}}.<br>Als u geen nieuwsbrief meer wilt ontvangen, kunt u zich <a style=\"color:#333;text-decoration:underline;font-size:13px;font-family:arial;font-weight:normal\" href=\"/tag/unsubscribe\">hier afmelden</a>.</td></tr></table></body>\n</html>",
	"import_url": "https://example.net/newsletter",
	"report": {
            "javascript": true,
            "no_unsubscribe": true
        }
    }
}

Campagne verzenden

Een campagne direct versturen.

Parameters

campaign_id (verplicht):

Het id van de campagne

Ter info: een campagne die al eerder verzonden werd, kan ook opnieuw verzonden worden. De campagne wordt dan alleen gestuurd naar de adressen die er sinds de laatste verzending zijn bijgekomen.

Definitie

POST https://api.laposta.nl/v2/campaign/{campaign_id}/action/send

Voorbeeld aanvraag

curl https://api.laposta.nl/v2/campaign/pbrqulw2tc/action/send \
  -u JdMtbsMq2jqJdQZD9AHC: \
  -X POST

Voorbeeld antwoord
{
    "campaign": {
        "account_id": "wFiUS4HL4e",
        "campaign_id": "pbrqulw2tc",
        "created": "2014-12-11 11:26:19",
        "modified": "2014-12-11 11:27:31",
        "type": "regular",
        "delivery_requested": "2014-12-11 11:27:29",
        "delivery_started": null,
        "delivery_ended": null,
        "name": "Mijn eerste campagne",
        "subject": "Mijn eerste campagne",
        "from": {
            "name": "Laposta API",
            "email": "api@laposta.nl"
        },
        "reply_to": "api@laposta.nl",
	"list_ids": {
            "kxhysrt26s": [
                "2noVadDLbd"
            ],
            "t1jmacge9a": [
                "GJn80BiYxo"
            ],
            "shb5vujyxj": [],
            "eiwhvx595g": [
                "PtIXMx2sG0"
            ]
        },
	"stats": {
	    "ga": "true",
	    "mtrack": "false"
	},
        "web": "https://laposta-api.email-provider.nl/web/wFiUS4HL4e/njhgaf61ye",
        "screenshot": {
            "113x134": "https://app.laposta.nl/clients/images/screenshots/9dknAdbAXm.2.png"
        }
    }
}

Campagne inplannen

Een campagne inplannen voor een later moment.

Parameters

campaign_id (verplicht):	Het id van de campagne
delivery_requested (verplicht):	Het moment van verzenden (formaat YYYY-MM-DD HH:MM:SS) in de tijdzone van het account

Ter info: een campagne die al eerder verzonden werd, kan ook opnieuw ingepland worden. De campagne wordt dan alleen verzonden naar de adressen die er sinds de laatste verzending zijn bijgekomen.

Definitie

POST https://api.laposta.nl/v2/campaign/{campaign_id}/action/schedule

Voorbeeld aanvraag

curl https://api.laposta.nl/v2/campaign/pbrqulw2tc/action/schedule \
  -u JdMtbsMq2jqJdQZD9AHC: \
  '-d delivery_requested=2016-05-19 12:00:00'

Voorbeeld antwoord
{
    "campaign": {
        "account_id": "wFiUS4HL4e",
        "campaign_id": "pbrqulw2tc",
        "created": "2014-12-11 11:26:19",
        "modified": "2014-12-11 11:27:31",
        "type": "regular",
        "delivery_requested": "2016-05-19 12:00:00",
        "delivery_started": null,
        "delivery_ended": null,
        "name": "Mijn eerste campagne",
        "subject": "Mijn eerste campagne",
        "from": {
            "name": "Laposta API",
            "email": "api@laposta.nl"
        },
        "reply_to": "api@laposta.nl",
	"list_ids": {
            "kxhysrt26s": [
                "2noVadDLbd"
            ],
            "t1jmacge9a": [
                "GJn80BiYxo"
            ],
            "shb5vujyxj": [],
            "eiwhvx595g": [
                "PtIXMx2sG0"
            ]
        },
	"stats": {
	    "ga": "true",
	    "mtrack": "false"
	},
        "web": "https://laposta-api.email-provider.nl/web/wFiUS4HL4e/njhgaf61ye",
        "screenshot": {
            "113x134": "https://app.laposta.nl/clients/images/screenshots/9dknAdbAXm.2.png"
        }
    }
}

Campagne testen

Een testmail versturen.

Parameters

campaign_id (verplicht):	Het id van de campagne
email (verplicht):	Het e-mailadres waarnaar de test verzonden moet worden.

Ter info: alleen bij een campagne waarvoor al wel inhoud is, maar die nog niet verzonden is, kan een testmail verstuurd worden.

Definitie

POST https://api.laposta.nl/v2/campaign/{campaign_id}/action/testmail

Voorbeeld aanvraag

curl https://api.laposta.nl/v2/campaign/pbrqulw2tc/action/testmail \
  -u JdMtbsMq2jqJdQZD9AHC: \
  -d email=test@example.net

Voorbeeld antwoord
{
    "campaign": {
        "account_id": "wFiUS4HL4e",
        "campaign_id": "pbrqulw2tc",
        "created": "2014-12-11 11:26:19",
        "modified": "2014-12-11 11:27:31",
        "type": "regular",
        "delivery_requested": null,
        "delivery_started": null,
        "delivery_ended": null,
        "name": "Mijn eerste campagne",
        "subject": "Mijn eerste campagne",
        "from": {
            "name": "Laposta API",
            "email": "api@laposta.nl"
        },
        "reply_to": "api@laposta.nl",
	"list_ids": {
            "kxhysrt26s": [
                "2noVadDLbd"
            ],
            "t1jmacge9a": [
                "GJn80BiYxo"
            ],
            "shb5vujyxj": [],
            "eiwhvx595g": [
                "PtIXMx2sG0"
            ]
        },
"stats": {
	    "ga": "true",
	    "mtrack": "false"
	},
        "web": "https://laposta-api.email-provider.nl/web/wFiUS4HL4e/njhgaf61ye",
        "screenshot": {
            "113x134": "https://app.laposta.nl/clients/images/screenshots/9dknAdbAXm.2.png"
        }
    }
}

Resultaten

De cijfers van de resultaten van campagnes opvragen.

URL patronen

/v2/report
/v2/report/{campaign_id}

Het object

Velden

account_id:	Het id van dit account
campaign_id:	Het id van de campagne
sent:	Het aantal verzonden e-mails
accepted:	Het aantal door de ontvangende mailservers geaccepteerde aantal e-mails
cleaned:	Het aantal opgeschoonde relaties
complained:	Het aantal spamklachten (door klikken op spamknop in e-mailprogramma)
hardbounced:	Het aantal hard-bounces
unsubscribed:	Het aantal afmeldingen
opened_unique:	Het aantal relaties dat de e-mail één keer of meer geopend heeft
clicked_unique:	Het aantal relaties dat één keer of meer geklikt heeft
webversion_unique:	Het aantal relaties dat de webversie heeft opgevraagd
accepted_ratio:	De verhouding geaccepteerde e-mails t.o.v. het aantal verzonden e-mails
opened_ratio:	De verhouding één keer of meer geopende e-mail t.o.v. het aantal geaccepteerde e-mails
clicked_ratio:	De verhouding e-mails waarin één keer of meer geklikt is t.o.v. het aantal geaccepteerde e-mails

Voorbeeld report object

{
    "report": {
        "account_id": "wFiUS4HL4e",
        "campaign_id": "njhgaf61ye",
	"sent": 20882,
        "accepted": 20139, 
        "cleaned": 744,
        "complained": 1,
        "hardbounced": 743,
        "unsubscribed": 184,
        "opened_unique": 5711,
        "clicked_unique": 1348,
        "webversion_unique": 64,
        "accepted_ratio": 0.96,
        "opened_ratio": 0.28,
        "clicked_ratio": 0.07
    }
}

Resultaten van campagne opvragen

De resultaten van een campagne.

Parameters

campaign_id (verplicht):

Het id van de campagne

Definitie

GET https://api.laposta.nl/v2/report/{campaign_id}

Voorbeeld aanvraag

$ curl https://api.laposta.nl/v2/report/njhgaf61ye \
  -u JdMtbsMq2jqJdQZD9AHC:

Voorbeeld antwoord
{
    "report": {
        "account_id": "wFiUS4HL4e",
        "campaign_id": "njhgaf61ye",
	"sent": 20882,
        "accepted": 20139, 
        "cleaned": 744,
        "complained": 1,
        "hardbounced": 743,
        "unsubscribed": 184,
        "opened_unique": 5711,
        "clicked_unique": 1348,
        "webversion_unique": 64,
        "accepted_ratio": 0.96,
        "opened_ratio": 0.28,
        "clicked_ratio": 0.07
    }
}

De resultaten van alle campagnes van een account opvragen

De resultaten van alle campagnes in een array van result objecten. De report objecten zijn opgenomen in een array met de naam 'data'.

Parameters

Geen.

Definitie

GET https://api.laposta.nl/v2/report

Voorbeeld aanvraag

$ curl https://api.laposta.nl/v2/report \
  -u JdMtbsMq2jqJdQZD9AHC:

Voorbeeld antwoord

{
    "data": [
	{
	    "report": {
		"account_id": "wFiUS4HL4e",
		"campaign_id": "njhgaf61ye",
		"sent": 20882,
		"accepted": 20139, 
		"cleaned": 744,
		"complained": 1,
		"hardbounced": 743,
		"unsubscribed": 184,
		"opened_unique": 5711,
		"clicked_unique": 1348,
		"webversion_unique": 64,
		"accepted_ratio": 0.96,
		"opened_ratio": 0.28,
		"clicked_ratio": 0.07
	    }
	},
	{
	    "report": {
		"account_id": "wFiUS4HL4e",
		"campaign_id": "keim8js77f",
		"sent": 6989,
		"accepted": 6863, 
		"cleaned": 126,
		"complained": 0,
		"hardbounced": 126,
		"unsubscribed": 260,
		"opened_unique": 3385,
		"clicked_unique": 1013,
		"webversion_unique": 120,
		"accepted_ratio": 0.98,
		"opened_ratio": 0.49,
		"clicked_ratio": 0.15
	    }
	}
    ]
}