API documentation

We would love to hear any questions and feedback you may have! Please mail us at api@laposta.org.

The API key used in the examples is available for testing.

The Laposta API has been set up according to the REST principle. All responses from the API, including error messages, have been formatted in JSON format.

The API primarily focuses on the addition and reading subscribers. This allows for Laposta to, among other things, synchronize with other systems, like a CMS or a CRM. Another of its common applications is the automatic addition of subscribers to Laposta, for instance when placing an order in a webshop.

It is also possible for partners to create accounts using the API, so that the set-up of customer accounts can fully be achieved without the need of our assistence.

In order to make programming with the API easier php and .NET (C#) libraries have been made available for users.

Default API URL

The API is available via http and https. For security reasons, we strongly recommend users to work with https URLs.

http://api.laposta.org/
https://api.laposta.org/

Available URL patterns

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

Authentication

Each request must include the account's API key. This can be found by logging in and proceeding to click on 'Access & Subscription' on the top right, and then going to 'Links - API'.

The Authentication process is achieved using Basic Authentication. The API-key functions as the username; a password is not required.

Example of request

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

Using the '-u' parameter, you will be able to pass the API key using Basic Authentication. Adding a colon behind the key avoids any password requests.

Rate limiting

In order to protect our systems, we have decided to limit the number of requests per unit of time. If you have reached a limit, you will recieve a notification from our server. This notification also indicates after how many seconds a next request is possible again.

For free accounts, there is a limit of 30 requests per minute. For paid accounts, the limit is 120 requests per minute.

Try to cache as much information as possible! For instance, it's not practical/necessary to create a sign-up form and then retrieve the information about the fields at every page view.

If the limit is reached

If you reach the limit, the server will respond with status code 429 (Too Many Requests). The server will also send a Retry-After header indicating the number of seconds to wait until the next request is possible.

Error messages

Our API uses as many standard HTTP status codes as possible in order to indicate how a request has proceeded. Codes in the 2xx range indicate a successful request, codes in the 4xx range indicate the presence of an error in the delivery of information (e.g. missing parameters), and codes in the 5xx range indicate that something went wrong on our end.

All error messages are formatted in JSON format and include an indication in regards to the type of error, a notification in regular language, and potentially a code with a parameter (in order to indicate the nature of the error).

Overview of used HTTP status codes

200 OK	Everything is in order
201 Created	Everything is in order, object created
400 Bad Request	Incomplete input
401 Unauthorized	No valid API key was provided
402 Request Failed	Input was in order, but request was not processed
404 Not Found	The requested object does not exist/could not be located
429 Too Many Requests	The maximum number of requests was reached within the given unit of time
500 Server Error	Error detected on Laposta's side

Overview of attributes in error messages

type	The nature of the error. This could be invalid_request for an error in the URL invocation, invalid_input for an error in the supplied data, or internal for an error in our system.
message	An explanation of the error in for humans intelligible language.
code	A numerical indication of the error (optional, see below).
parameter	The parameter concerning the error (optional).

Overview of codes in error messages

201	The parameter is empty
202	The syntax of the parameter is incorrect
203	The parameter is unknown
204	The parameter already exists
205	The parameter is not a number
206	The parameter is not a boolean (true/false)
207	The parameter is not a date
208	The parameter is not an email address
209	The parameter is not a URL
999	The parameter contains another error

Example of an error object

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

Lists

This element allows the user to retrieve, add, modify, delete and empty lists.

URL patterns

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

URL patterns

Fields

list_id:	ID of the list in question
created:	Date and time of creation
modified:	Date and time of last modification made
state:	Status of the list: `active` or `deleted`
name:	Name given to the list in question
remarks:	Potential remarks
subscribe_notification_email:	Email address to which a notification will be sent upon a subscription
unsubscribe_notification_email:	Email address to which a notification will be sent upon the cancelling of a subscription
members:	Information in regards to the number of active, unsubscribed and cleaned (deleted) members

Example of list object

{
    "list": {
  	"list_id": "BaImMu3JZA",
  	"created": "2012-02-18 11:42:38",
  	"modified": "2012-06-02 14:07:20",
	"state": "active",
  	"name": "Testlist",
  	"remarks": "A list for testing purposes",
	"subscribe_notification_email": "subscription@example.net",
	"unsubscribe_notification_email": "unsubscription@example.net",
	"members": {
		"active": 1232,
		"unsubscribed": 113,
		"cleaned": 14
        }
    }
}

Adding a list

If there is something wrong with the parameters provided, a code is displayed with an error message. You may use these in combination with the variable 'parameter' to display a message to the user. See above under 'Error messages' what the codes stand for.

Parameters

name (mandatory):	Name given to the list in question
remarks:	Potential remarks
subscribe_notification_email:	Email address to which a notification will be sent upon a subscription
unsubscribe_notification_email:	Email address to which a notification will be sent upon the cancelling of a subscription

Definition

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

Example of request

$ curl https://api.laposta.org/v2/list \
  -u JdMtbsMq2jqJdQZD9AHC: \
  -d name=Testlist \
  '-d remarks=A list for testing purposes.' \
  -d subscribe_notification_email=subscription@example.net \
  -d unsubscribe_notification_email=unsubscription@example.net

Example of response

{
    "list": {
  	"list_id": "BaImMu3JZA",
  	"created": "2012-02-18 11:42:38",
  	"modified": "2012-06-02 14:07:20",
	"state": "active",
  	"name": "Testlist",
  	"remarks": "A list for testing purposes.",
	"subscribe_notification_email": "subscription@example.net",
	"unsubscribe_notification_email": "unsubscription@example.net",
	"members": {
		"active": 0,
		"unsubscribed": 0,
		"cleaned": 0
        }
    }
}

Requesting a list

All information about a list.

Parameters

list_id (mandatory):

The list's ID

Definition

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

Example of request

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

Example of response
{
    "list": {
	"list_id": "BaImMu3JZA",
	"created": "2012-02-18 11:42:38",
	"modified": "2012-06-02 14:07:20",
	"state": "active",
	"name": "Testlist",
	"remarks": "A list for testing purposes",
	"subscribe_notification_email": "subscription@example.net",
	"unsubscribe_notification_email": "unsubscription@example.net",
	"members": {
		"active": 1232,
		"unsubscribed": 113,
		"cleaned": 14
	}
    }
}

Modifying lists

You will only have to include the fields that need to be modified in the application. Fields that are not mentioned will keep their current value. As soon as a field is mentioned, it is checked and may therefore cause an error message. A code is displayed with this error message. You may use this code in combination with the variable 'parameter' to display a message to the user. See above under 'Error messages' what the codes stand for.

Parameters

list_id (mandatory):	The ID of the list that has to be modified
name:	A name for the list in question
remarks:	Potential remarks
subscribe_notification_email:	Email address to which a notification will be sent upon a subscription
unsubscribe_notification_email:	Email address to which a notification will be sent upon the cancelling of a subscription

Definition

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

Example of request

This example changes the name.

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

Example of response

{
    "list": {
        "list_id": "BaImMu3JZA",
        "created": "2012-02-18 11:42:38",
        "modified": "2012-06-02 14:07:20",
	"state": "active",
        "name": "Customers",
        "remarks": "A list for testing purposes.",
	"subscribe_notification_email": "subscription@example.net",
	"unsubscribe_notification_email": "unsubscription@example.net",
	"members": {
		"active": 1232,
		"unsubscribed": 113,
		"cleaned": 14
        }
    }
}

Deleting a list

This permanently deletes a list. If the list does not exist, an error message is displayed. In response you are shown another list object, but now with the state 'deleted'. After having finished this procedure, it is no longer possible for the user to request the list.

Parameters

list_id (mandatory):

The ID of the list

Definition

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

Example of request

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

Example of response

{
    "list": {
        "list_id": "BaImMu3JZA",
        "created": "2012-02-18 11:42:38",
        "modified": "2012-06-02 14:07:20",
	"state": "deleted",
    	"name": "Customers",
        "remarks": "A list for testing purposes",
	"subscribe_notification_email": "subscription@example.net",
	"unsubscribe_notification_email": "unsubscription@example.net",
	"members": {
		"active": 1232,
		"unsubscribed": 113,
		"cleaned": 14
        }
    }
}

Requesting all lists

All lists in an array of list objects. The list objects have been ordered in an array with the name 'data'.

Parameters

No parameters need to be provided.

Definition

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

Example of request

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

Example of response

{
    "data": [
        {
            "list": {
                "list_id": "BaImMu3JZA",
                "created": "2012-02-18 11:42:38",
                "modified": "2012-06-02 14:07:20",
		"state": "active",
                "name": "Testlist",
                "remarks": "A list for testing purposes.",
        	"subscribe_notification_email": "subscription@example.net",
        	"unsubscribe_notification_email": "unsubscription@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": "Another list",
                "remarks": "Customers",
        	"subscribe_notification_email": "subscription@example.net",
        	"unsubscribe_notification_email": "unsubscription@example.net"
		"members": {
			"active": 8182,
			"unsubscribed": 205,
			"cleaned": 56
		}
            }
	}
    ]
}

Purging a list

This permanently purges all active subscribers from a list, but doesn't delete the list itself. If the list does not exist, an error message is displayed. In response, you are shown another list object.

Parameters

list_id (mandatory):

The ID of the list

Definition

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

Example of request

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

Example of response

{
    "list": {
        "list_id": "BaImMu3JZA",
        "created": "2012-02-18 11:42:38",
        "modified": "2012-06-02 14:07:20",
	"state": "deleted",
    	"name": "Customers",
        "remarks": "A list for testing purposes",
	"subscribe_notification_email": "subscription@example.net",
	"unsubscribe_notification_email": "unsubscription@example.net",
	"members": {
		"active": 1232,
		"unsubscribed": 113,
		"cleaned": 14
        }
    }
}

Filling / editing a list (in bulk)

This feature is not available for free accounts.

Allows you to modify and/or simultaneously add several relations to an existing list. If the list does not exist or if mandatory parameters are missing, you will receive an error message. Please note that data delivery is via JSON.

Parameters

list_id (mandatory):

The ID of the list

JSON Object

mode (mandatory):	The mode of the request: edit, add, or add_and_edit. In the mode add only new relations are added and data from existing relations are ignored. In the mode edit new relations are ignored and data of existing relations are modified. In the mode add_and_edit new relations are added and data of existing relations are modified.
members (mandatory):	An array with member objects. A minimum of 1, maximum of 100,000.

Member Object

member_id (occasionally mandatory):	The ID OR email address of the relation. If specified, must appear in the list.
email (occasionally mandatory):	The email address of the relation to be changed or added. If the member_id is also specified, then a new email address can be specified here for the existing relation.
custom_fields (occasionally mandatory):	A JSON object where the key is the name of the extra field and the value is the value of the extra field.
source_url:	The URL from which the relation was registered.

The member_id field is mandatory if the email field is missing. If member_id is specified, then the matching relation is queried in the list and then updated accordingly.
The email field is mandatory if the member_id field is missing. If there is an email but no member_id, we query the list for a matching relation based on the email. If it is located, we update the matching relation. If it is not located, we add a new relation.
A custom field may be mandatory if you have mandatory fields in the list. A custom field is never mandatory for an existing relation.
For relations added through this method, we equate the IP address with the server from which the request originates.

Definition

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

Example of request

$ curl --json '{json_string}' https://api.laposta.org/v2/list/BaImMu3JZA/members \
  -u JdMtbsMq2jqJdQZD9AHC: \
  -X POST
The {json_string} must be a well articulated JSON string which meets the conditions specified at 'JSON OBJECT'. A legible example:

{
    "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"
            }
        }
    ]
}

Example of response

First of all, an error message may be reported back as described under error messages. This happens when the request is rejected on the basis of an unsubmitted or incorrectly submitted list_id, or when the embedded JSON data is not correct.

If there is no error message as described above, we always send out a successful response in accordance with the following example of the 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"
                }
            }
        }
    ]
}

As illustrated in the example above, you will receive a report, and we sort the provided member objects into errors, skipped, edited, and added. You will always receive this report from us, even if there is no data in it. For every member we process, you will receive the provided_data, and wherever possible you will also receive a member object the way as the member is currently known to us in the system. This way you will be able to easily compare the submitted list with the status at Laposta. Members end up in skipped when, according to the given mode, they are not allowed to be processed but have been included regardless.

Fields

This section allows you to request, add and modify fields of lists.

URL patterns

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

The field object

Fields

field_id:	The ID of the field in question
list_id:	The ID of the list to which the field belongs
created:	Date and time of creation
modified:	Date and time of last modification made
state:	The status of the field in question: either `active` or `deleted`
name:	Name of the field (for displaying purposes)
tag:	The subscriber variable for usage in campaigns (not modifyable)
custom_name:	Name of the field (for use in member API calls)
defaultvalue:	The default value (will be used in the absence of this field)
datatype:	The data type of the field in question (`text`, `numeric`, `date`, `select_single`, `select_multiple`)
datatype_display:	Only applicable for select_single: the desired display (`select`, `radio`)
options:	An array of the available options (only for `select_single` or `select_multiple`)
options_full:	An array of the available options, including IDs (alleen bij `select_single` or `select_multiple`)
required:	Is this a mandatory field? (`true` or `false`)
in_form:	Does this field occur in the subscription form? (`true` or `false`)
in_list:	Does this field occur while browsing the list? (`true` or `false`)
autocomplete:	The value for the html autocomplete attribute (`string`)

Example of 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": "Name",
        "tag": "{{name}}",
        "custom_name": "name",
        "defaultvalue": "",
        "datatype": "text",
        "datatype_display": null,
        "required": true,
        "in_form": true,
        "in_list": true,
	"autocomplete": "on"
    }
}

Adding a field

If there is something wrong with the parameters provided, a code is displayed with an error message. See above under 'Error messages' what the codes stand for.

Parameters

list_id (mandatory):	The ID of the list to which the field belongs
name (mandatory):	A name for this field
defaultvalue:	A potential default value
datatype (mandatory):	The data type: `text`, `numeric`, `date`, `select_single` or `select_multiple`
datatype_display:	Only applicable for select_single: the desired display (`select`, `radio`)
options:	What selection options are available? (mandatory for the data types `select_single` of `select_multiple`). The options can be given as an array. In the answer the options are repeated, but there is also an extra field `options_full`. Also listed are the option IDs, which may eventually be used to change the options later.
required (mandatory):	Is this a mandatory field?
in_form (mandatory):	Does this field occur in the subscription form? (`boolean`)
in_list (mandatory):	Is this field visible in Laposta's overview? (`boolean`)

Definition

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

Example of request

curl https://api.laposta.org/v2/field \
  -u JdMtbsMq2jqJdQZD9AHC: \
  -d list_id=srbhotdwob \
  -d name=Color \
  -d defaultvalue=Green \
  -d datatype=select_single \
  -d datatype_display=radio \
  -d options[]=Red \
  -d options[]=Green \
  -d options[]=Blue \
  -d required=true \
  -d in_form=true \
  -d in_list=true

Example of response

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

Requesting a field

All information about a field.

Parameters

list_id (mandatory):	The ID of the list to which the field belongs
field_id (mandatory):	The ID of the requestable field

Definition

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

Example of request

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

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

Modifying fields

You will only have to include the parts that need to be modified. Parts that are not mentioned will keep their current values. As soon as a part is mentioned it does get checked, and thus can cause an error message. This error message contains a code with a message. See above under 'Error messages' what these codes stand for.

Please note that changing the data type removes all data from the field in question.

Parameters

list_id (mandatory):	The ID of the list to which the field belongs
name:	A name for this field
datatype:	The data type of this field (`text`, `numeric`, `date`, `select_single`, `select_multiple`)
datatype_display:	Only applicable for select_single: the desired display (`select`, `radio`)
options:	What selection options are available? Array with values only. Please note that this list replaces the existing options in its entirety. To modify fields already in use, it is preferable to use `options_full`. (Only possible for data types `select_single` or `select_multiple`)
options_full:	What selection options are there? Array with per option both the value (`value`) and the ID (`ID`). If IDs match, the corresponding option is modified. (Only possible for data types `select_single` of `select_multiple`)
defaultvalue:	The default value (will be used in the absence of this field)
required:	Is this a mandatory field?
in_form:	Does this field occur in the subscription form? (`boolean`)
in_list:	Is this field visible in Laposta's overview? (`boolean`)

Definition

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

Example of request

This example makes the field no longer mandatory.

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

Example of response

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

Deleting a field

This permanently deletes a field. If the field does not exist, an error message is displayed. In response you are shown another field object, but now with the state 'deleted'. After having finished this procedure, it is no longer possible for the user to request the field.

Parameters

field_id (mandatory):	The ID of the field to be deleted
list_id (mandatory):	The ID of the list to which the field belongs

Definition

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

Example of request

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

Example of response

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

Requesting all fields of a list

All fields of a list in an array of field objects. The field objects are formatted in an array named 'data'.

Parameters

list_id (mandatory):

The ID of the list to which the field belongs

Definition

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

Example of request

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

Example of response

{
    "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": "Name",
		"tag": "{{name}}",
		"custom_name": "name",
		"defaultvalue": "reader",
		"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": "Age",
		"tag": "{{age}}",
		"custom_name": "age",
		"defaultvalue": "unknown",
		"datatype": "date",
		"required": true,
		"in_form": true,
		"in_list": true,
		"autocomplete": "on"
	    }
	}
    ]
}

Subscribers

This section allows you to retrieve, add and modify subscribers.

You will need a list_id as a parameter each time. You can find this by logging in, and proceeding to the corresponding list under 'Subscribers'. Next up, click on the tab labeled 'Attributes list'. On the right side you will see the ID there.

URL patterns

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

The member object

Fields

member_id:	The ID of this member object
list_id:	The ID of the related list
email:	The email address
state:	The current status of this subscriber: `active`, `unsubscribed`, `unconfirmed` or `cleaned`
signup_date:	Date and time of subscription, format YYYY-MM-DD HH:MM:SS
modified:	Date and time of last modification made, format YYYY-MM-DD HH:MM:SS
ip:	IP from which the subscriber is registered
source_url:	URL from which the subscriber is registered
custom_fields:	An array with the value of all additional fields of the corresponding list. If there are fields where several options can be selected, these options are listed in an array..

Example of 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"
            ]
        }
    }
}

Adding a subscriber

If there is something wrong with the parameters provided, a code is displayed with an error message. You can use this in combination with the variable 'parameter' to display a message to the user. See above under 'Error messages' what the codes stand for.

Parameters

list_id (mandatory):	The ID of the list to which the subscriber must be added
ip (mandatory):	The IP address from which the subscriber is registered
email (mandatory):	The email address of the subscriber to be added
source_url:	The URL from which the subscriber is registered
custom_fields:	The values of the extra fields. The name (key) of the field is the 'custom_name' (part of the Field object). This is the same as the 'Variable' in the application.
options:	Additional instructions, with possibilities being: `upsert: true` to overwrite fields if the email address is already linked to an active contact in this list. Normally, you would receive an error if the email address is already linked to an active contact. Note: If a subscriber is unsubscribed and you perform an upsert with that email address, it will be set to active again. If you want to prevent an unsubscribed subscriber from being reactivated, you can use the `suppress_reactivation` option. `suppress_reactivation: true` to prevent an unsubscribed subscriber from being reactivated during an upsert `suppress_email_notification: true` to prevent a notification email from being sent every time someone logs in via an API `ignore_doubleoptin: true` to instantly activate subscribers on a double-optin list and ensure that no confirmation email is sent when signing up through the API.

If it concerns a double-optin list then a confirmation email will be sent with each subscription, unless the 'ignore_doubleoptin' option is included (see above).

If there are custom_fields that have been set to mandatory, then filling these fields via the API is also mandatory.

Definition

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

Example of request

$ curl https://api.laposta.org/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

Multiple choice custom fields can be filled with the currently defined options for that field. So you can simply enter the value of the field. If multiple choices can be made, you can pass them in an array; see the example above.

Example of response

{
    "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"
            ]
        }
    }
}

Requesting a subscriber

All information about a subscriber in a member object

Parameters

list_id (mandatory):	The ID of the list in which the subscriber appears
member_id (mandatory):	The ID or the email address of the subscriber

Definition

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

Example of request

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

You may also use the email address here instead of the member_id. Please note that a '+' in the address should be displayed as: %252B

Example of response

{
    "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"
            ]
        }
    }
}

Modifying a subscriber

You only have to include the fields that need to be modified in the request. Fields that are not named will keep their current value. As soon as a field is mentioned it does get checked, and thus can cause an error message. This error message displays a code with a message. See above under 'Error messages' what the codes stand for.

Parameters

list_id (mandatory):	The ID of the list to which the subscriber must be modified
email:	The email address of the subscriber that must be modified
state:	The new status of the subscriber: active or unsubscribed
custom_fields:	The values of the extra created fields

Definition

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

Example of request

This example changes the name and the amount of children

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

Instead of using the member_id, you may also use the email address

Multiple choice custom fields that are not mandatory can be emptied by including the variable in the change request, but without an assigned value.

Example of response

{
    "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"
            ]
        }
    }
}

Deleting a subscriber

This permanently deletes a subscriber. If the subscriber does not exist, an error message is displayed. In response you are shown another list object, but now with the state 'deleted'. After having finished this procedure, it is no longer possible for the user to request the subscriber.

Parameters

list_id (mandatory):

The ID of the list in which the subscriber appears

Definition

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

Example of request

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

You may also use the email address here instead of the member_id.

Example of response

{
    "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"
            ]
        }
    }
}

Requesting all subscribers of a list

All fields of a list in an array of member objects. The member objects are formatted in an array named 'data'.

Parameters

list_id (mandatory):	The ID of the list from which the subscribers are being requested
state:	The status of the requested subscribers: active, unsubscribed or cleaned

Definition

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

Example of request

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

Example of response

{
    "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 are a separate part of the API. With the normal API, the request for information always comes from the developer. With webhooks it is the other way around and Laposta takes the initiative to inform the developer of something. A webhook does this by querying a URL that you have specified; in the form of a POST with a JSON object containing information.

You can enter URLs for adding, changing or deleting subscribers. Let us suppose you create a webhook for additions, and someone registers via a Laposta registration form, then almost immediately after this new registration you will receive a POST at the URL you have specified.

Application: Syncronization with other systems

Our API is mainly used to synchronize the subscribers file in Laposta with another application, for example a CMS or a CRM. Adding and changing subscribers to Laposta is then aclished via the API (as described above). Webhooks notify your application of modifies in the subscriber file that take place within Laposta (subscriptions, the cancelling of subscriptions, or modifications). With the combination of these two functions, you are able to keep the two files in sync.

The processing of webhooks

With a webhook, a URL is requested on your server. You are completely in control of how that information is processed. To indicate that you have received a webhook correctly, the server must return a 200 HTTP status code. (This will usually be the case by default).

After modifications via the API

By default, the webhooks are not called when you add or modify relationships via the API. The reasoning behind this is that you are already aware of the changes, and receiving this information via a webhook would be redundant. However, there may be situations where this is desired (for example, if the API is called from an external form). This is possible; if you send us an email about this, we can activate it.

Registering webhooks

You can register webhooks per list. This is done by going to the appropriate list (under Subscribers), and proceeding to the Attributes list. There, you will find the tab called Webhooks.

For each webhook, you can specify the event for which it should be requested: adding a subscriber, modifying a subscriber, or deleting a subscriber. In addition, you specify the URL to which the information should be POSTed.

It is possible to moderate the webhooks through this API; please see the information below.

Timing

It may happen that calling up a webhook fails, for example, because your server is not accessible or produces an error message. Laposta will then continue to offer the webhook a number of times (7, to be exact). First after 5 minutes and then in increasing intervals of up to about 14 days. If no contact has been made by then, the webhook is deleted.

Bundling events

Every 5 seconds, the present webhooks are called. If there happen to be several, they are bundled together, up to a maximum of 1000 events per request. This prevents your server from being overloaded with requests, e.g. when importing larger numbers of subscribers into Laposta.

Structure of a webhook

You will receive an object in JSON format from the URL you have specified. This object consists of an array with the name data, in which the different events are listed. This means that several events can be included in a single request (see above under 'Bundling events')..

Fields

type:	The type of webhook (always member)
event:	The reason why the webhook has been requested. Could be: subscribed, modified or deactivated
data:	The data of the object that has been added, modified or deleted. In this case, a member object
info:	Extra information in regards to the request of the webhook, see below
date_requested:	The time at which this request was sent

Fields info object

date_event:

The moment this event occurred (and at the same time the moment the webhook was triggered)

action (optional):

Extra information in regards to the event, different options for the various events. For the event subscribed:

subscribed:	Relation added
resubscribed:	Relation readded

For the event deactivated:

unsubscribed:	Relation unsubscribed
deleted:	Relation deleted
hardbounce:	Relation deleted after hard bounce

source (optioneel):

Source of the event: could be app (within the web interface) or external (via, for example, a subscription form)

Example of 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
}

Managing webhooks

You can also manage the webhooks with the API. Below is explained how to retrieve, add and modify webhooks.

URL patterns

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

The webhook object

Fields

webhook_id:	The ID of this webhook
list_id:	The ID of the list to which the field belongs
created:	Date and time of creation
modified:	Date and time of last modification made
state:	The status of this webhook: `active` or `deleted`
event:	When will the webhook be requested? (`subscribed`, `modified` or `deactivated`)
url:	The URL to be accessed
blocked:	Is the accessing of the webhook (temporarily) blocked? (`true` or `false`)

Example of 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
    }
}

Adding a webhook

If there is something wrong with the parameters provided, a code is displayed with an error message. See above under 'Error messages' what the codes stand for.

Parameters

list_id (mandatory):	The ID of the list to which the field belongs
event (mandatory):	When will the webhook be requested? (`subscribed`, `modified` of `deactivated`)
url (mandatory):	The URL to be accessed
blocked (mandatory):	Is the accessing of the webhook (temporarily) blocked? (`true` or `false`)

Definition

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

Example of request

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

Example of response

{
    "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
    }
}

Requesting a webhook

All information about a webhook

Parameters

list_id (mandatory):	The ID of the list to which the field belongs
webhook_id(mandatory):	The ID of the list to be requested

Definition

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

Example of request

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

Example of response
{
    "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
    }
}

Modifying a webhook

If there is something wrong with the parameters provided, a code is displayed with an error message. Fields that are not mentioned will keep their current value fields keep their current value. As soon as a field is mentioned it does get checked, and thus can cause an error message. This error message displays a code with a message. See above under 'Error messages' what the codes stand for. See above under 'Error messages' what the codes stand for.

Parameters

list_id (mandatory):	The ID of the list to which the field belongs
webhook_id(mandatory):	The ID of the list to be requested
event:	When will the webhook be requested? (`subscribed`, `modified` or `deactivated`)
url:	The URL to be accessed
blocked:	Is the accessing of the webhook (temporarily) blocked? (`true` or `false`)

Definition

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

Example of request

This example modifies the URL

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

Example of response

{
    "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
    }
}

Deleting a webhook

This permanently deletes a webhook. Potentially outstanding requests from the webhook will still be completed. If the field does not exist, an error message is displayed. In response you are shown another webhook object, but now with the state 'deleted'. After having finished this procedure, it is no longer possible for the user to request the webhook.

Parameters

field_id (mandatory):	The ID of the webhook to be deleted
list_id (mandatory):	The ID of the list to which the webhook belongs

Definition

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

Example of request

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

Example of response

{
    "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
    }
}

Requesting all webhooks of a list

All webhooks of a list in an array of member objects. The webhook objects are formatted in an array named 'data'.

Parameters

list_id (mandatory):

The ID of the list to which the webhooks belong

Definition

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

Example of request

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

Example of response

{
    "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
	    }
	}
    ]
}

Campaigns

Retrieving, creating, filling and sending campaigns.

URL patterns

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

The campaign object

Fields

account_id:	The ID of this account
campaign_id:	The ID of this campaign
created:	Date and time of creation
modified:	Date and time of last modification made
type:	The type of campaign (currently only possible: `regular`)
delivery_requested:	When to send
delivery_started:	Start of last transmission
delivery_ended:	End of last transmission
name:	Internal name of campaign
subject:	Subject line
from:	Sender (name en email address)
reply_to:	Email address for receiving replies
list_ids:	Linked lists and segments
stats:	Linked web statistics
web:	URL to web version
screenshot:	Screenshots of campaign

Example of 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": "My first campaign",
        "subject": "My first campaign",
        "from": {
            "name": "Laposta API",
            "email": "api@laposta.org"
        },
        "reply_to": "api@laposta.org",
	"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.org/clients/images/screenshots/9dknAdbAXm.2.png"
            "226x268": "https://app.laposta.org/clients/images/screenshots/9dknAdbAXm.2.png"
        }
    }
}

Creating a campaign

Parameters

type (mandatory):	Type of campaign (must be set to: `regular`)
name (mandatory):	A name for this campaign for internal use
subject (mandatory):	Subject line
from[name] (mandatory):	The name of the sender
from[email] (mandatory):	The email address of the sender (must be a sender address approved within the program)
reply_to:	Email address for receiving replies
list_ids (mandatory):	Recipients, array of list_ids and segment_ids if needed
stats[ga]:	Link Google Analytics (`true` or `false`)
stats[mtrack]:	Link Mtrack (`true` or `false`)

The campaign has not yet been filled or scheduled after the request. Use the /content and /action patterns in order to do this, see below.

Definition

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

Example of request

$ curl https://api.laposta.org/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

Example of response

{
    "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.org/clients/images/screenshots/default/113x134_nl.png",
            "226x268": "https://app.laposta.org/clients/images/screenshots/default/113x134_nl.png"
        }
    }
}

Requesting a campaign

All information about a campaign

Parameters

campaign_id (mandatory):

The ID of the campaign

Definition

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

Example of request

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

Example of response
{
    "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": "My first campaign",
        "subject": "My first campaign",
        "from": {
            "name": "Laposta API",
            "email": "api@laposta.org"
        },
        "reply_to": "api@laposta.org",
	"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.org/clients/images/screenshots/9dknAdbAXm.2.png"
        }
    }
}

Modifying a campaign

You only have to submit the fields that require to be modified in the application. Fields that are not mentioned will keep their current value fields keep their current value. As soon as a field is mentioned it does get checked, and thus can cause an error message. This error message displays a code with a message. See above under 'Error messages' what the codes stand for.

Parameters

campaign_id (mandatory):	The ID of the campaign that has to be modified
name:	A name for this campaign for internal use
subject:	Subject line
from[name]:	The name of the sender
from[email]:	The email address of the sender (must be a sender address approved within the program)
reply_to:	Email address for receiving replies
list_ids:	Recipients, array of list_ids and segment_ids if needed
stats[ga]:	Link Google Analytics (`true` or `false`)
stats[mtrack]:	Link Mtrack (`true` or `false`)

Definition

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

Example of request

This example changes the subject line.

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

Example of response

{
    "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.org/clients/images/screenshots/default/113x134_nl.png",
            "226x268": "https://app.laposta.org/clients/images/screenshots/default/113x134_nl.png"
        }
    }
}

Deleting a campaign

This deletes a campaign. Unsent campaigns will be permanently deleted. Campaigns that have been sent are permanently deleted only after 180 days. In the meantime, they can be restored in the overview of campaigns in our program.

In response you are shown another campaign object, but now with the state 'deleted'. After having finished this procedure, it is no longer possible for the user to request the campaign.

Parameters

campaign_id (mandatory):

The ID of the campaign to be deleted

Definition

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

Example of request

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

Example of response

{
    "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.org/clients/images/screenshots/default/113x134_nl.png",
            "226x268": "https://app.laposta.org/clients/images/screenshots/default/113x134_nl.png"
        },
        "state": "deleted"
    }
}

Requesting all campaigns of an account

All campaigns in an array of campaign objects. The campaign objects have been ordered in an array with the name 'data'.

Parameters

None.

Definition

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

Example of request

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

Example of response

{
    "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": "My first campaign",
                "subject": "My first campaign",
                "from": {
                    "name": "Laposta API",
                    "email": "api@laposta.org"
                },
                "reply_to": "api@laposta.org",
		"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.org/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": "My second campaign",
                "subject": "My second campaign",
                "from": {
                    "name": "Laposta API",
                    "email": "api@laposta.org"
                },
                "reply_to": "api@laposta.org",
		"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.org/clients/images/screenshots/ClCvez9GXQ.2.png"
                }
            }
        }
    ]
}

Requesting campaign content

Requesting the content of a campaign.

Please note that this is only possible if it involves a campaign that has been exported, and not for a campaign created within the application using the drag & drop editor.

Parameters

campaign_id (mandatory):

The ID of the campaign

Definition

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

Example of request

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

Example of response
{
    "campaign": {
        "account_id": "wFiUS4HL4e",
        "campaign_id": "pbrqulw2tc",
        "plaintext": "View the web version here:\n/tag/web\n\n           \n\n \t\tInsert a short and captivating description of your newsletter here.\n\n \t\tView the web version [1]\n\n \t\tTitle of this segment\n\n This is a text segment. If you click this text, you can edit\nthis. On the left side you are presented with two tabs. Under the Content\ntab, you can enter your text and do some formatting. Here you may also edit the\ntitle of this segment. Under the Formatting tab, you will be able to deal with the main\nformatting, of the title, the text and the box.\n\nWould you like to return to the overview of segments and the options for overall\nlayout? Save your segment or click the outside of your\nnewsletter. \n\n This email has been sent to {{email}} [2].\nIf you no longer wish to receive our newsletter, you may unsubscribe here\n[3].\nYou may also review and modify your data [4].\nFor proper delivery, please add {{from_email}} [5] to your\ncontact book. \n\nThis email has been sent to {{email}}.\nIf you no longer wish to receive our newsletter, you may unsubscribe here\n\n[6].\n\n \n\nLinks:\n------\n[1] http://clients.laposta.org/tag/web\n[2] mailto:{{email}}\n[3] http://clients.laposta.org/tag/unsubscribe\n[4] http://clients.laposta.org/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\">This email has been sent to {{email}}.<br>If you no longer wish to receive our newsletter, you may unsubscribe <a style=\"color:#333;text-decoration:underline;font-size:13px;font-family:arial;font-weight:normal\" href=\"/tag/unsubscribe\">here</a>.</td></tr></table></body>\n</html>",
	"import_url": "https://example.net/newsletter"
    }
}

Filling campaign content

Filling in the content of a campaign

Parameters

The campaign can either be filled directly with html, or through a URL, in which case Laposta imports the html found at the specified URL. One of the two must be chosen. If both parameters are given the html is taken.

campaign_id (mandatory):	The ID of the campaign
html:	The html for the campaign
import_url:	The URL from which the html must be imported
inline_css:	Potential inlining of css (`true` or `false`)

Report result

If the import fails, a 400 error message from the API will occur. If it does succeed in importing the html, but problems were found during the import, they are shown in the variable report in the response. These may include:

javascript:	JavaScript was encountered
flash:	Flash was encountered
no_unsubscribe:	No unsubscribe could be located
empty_unsubscribe:	Empty unsubscribe encountered
css:	Missing external css files (listed)
images:	Missing external images (listed)

Solving these problems is not necessary in order to properly send the newsletter, but it is highly recommended.

Advertising and unsubscribe link

In the case of a free account, our advertising is added to the bottom of the newsletter. If the offered html does not contain an unsubscribe link, it will simply be added by our program.

Definition

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

Example of request

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

Example of response
{
	   "campaign": {
	       "account_id": "wFiUS4HL4e",
	       "campaign_id": "pbrqulw2tc",
	       "plaintext": "View the web version here:\n/tag/web\n\n           \n\n \t\tInsert a short and captivating description of your newsletter here.\n\n \t\tView the web version [1]\n\n \t\tTitle of this segment\n\n This is a text segment. If you click this text, you can edit\nthis. On the left side you are presented with two tabs. Under the Content\ntab, you can enter your text and do some formatting. Here you may also edit the\ntitle of this segment. Under the Formatting tab, you will be able to deal with the main\nformatting, of the title, the text and the box.\n\nWould you like to return to the overview of segments and the options for overall\nlayout? Save your segment or click the outside of your\nnewsletter. \n\n This email has been sent to {{email}} [2].\nIf you no longer wish to receive our newsletter, you may unsubscribe here\n[3].\nYou may also review and modify your data [4].\nFor proper delivery, please add {{from_email}} [5] to your\ncontact book. \n\nThis email has been sent to {{email}}.\nIf you no longer wish to receive our newsletter, you may unsubscribe here\n\n[6].\n\n \n\nLinks:\n------\n[1] http://clients.laposta.org/tag/web\n[2] mailto:{{email}}\n[3] http://clients.laposta.org/tag/unsubscribe\n[4] http://clients.laposta.org/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\">This email has been sent to {{email}}.<br>If you no longer wish to receive our newsletter, you may unsubscribe <a style=\"color:#333;text-decoration:underline;font-size:13px;font-family:arial;font-weight:normal\" href=\"/tag/unsubscribe\">here</a>.</td></tr></table></body>\n</html>",
	"import_url": "https://example.net/newsletter",
	"report": {
            "javascript": true,
            "no_unsubscribe": true
        }
    }
}

Sending a campaign

Directly sending a campaign

Parameters

campaign_id (mandatory):

The ID of the campaign

Note: A campaign that has been sent before can also be re-sent. The campaign will then only be sent to the addresses that have been added since the last send.

Definition

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

Example of request

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

Example of response
{
    "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": "My first campaign",
        "subject": "My first campaign",
        "from": {
            "name": "Laposta API",
            "email": "api@laposta.org"
        },
        "reply_to": "api@laposta.org",
	"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.org/clients/images/screenshots/9dknAdbAXm.2.png"
        }
    }
}

Planning a campaign

Planning a campaign for a later date.

Parameters

campaign_id (mandatory):	The ID of the campaign
delivery_requested (mandatory):	The time and date of sending (format YYYY-MM-DD HH:MM:SS) in the accounts timezone

Note: A campaign that has been sent before can also be re-planned. The campaign will then only be sent to the addresses that have been added since the last send.

Definition

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

Example of request

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

Example of response
{
    "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": "My first campaign",
        "subject": "My first campaign",
        "from": {
            "name": "Laposta API",
            "email": "api@laposta.org"
        },
        "reply_to": "api@laposta.org",
	"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.org/clients/images/screenshots/9dknAdbAXm.2.png"
        }
    }
}

Testing a campaign

Sending a test mail

Parameters

campaign_id (mandatory):	The ID of the campaign
email (mandatory):	The email address to which the test should be sent.

Note: only in the case of a campaign for which there already is content, but which has not yet been sent, is it possible for a test email to be sent.

Definition

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

Example of request

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

Example of response
{
    "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": "My first campaign",
        "subject": "My first campaign",
        "from": {
            "name": "Laposta API",
            "email": "api@laposta.org"
        },
        "reply_to": "api@laposta.org",
	"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.org/clients/images/screenshots/9dknAdbAXm.2.png"
        }
    }
}

Results

Retrieve the figures of the results of campaigns.

URL patterns

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

The object

Fields

account_id:	The ID of this account
campaign_id:	The ID of the campaign
sent:	The number of emails sent
accepted:	The number of emails accepted by the recipient mail servers
cleaned:	The number of deleted subscribers
complained:	The number of spam complaints (by clicking on the spam button in the email program)
hardbounced:	The number of hard-bounces
unsubscribed:	The number of unsubscriptions
opened_unique:	The number of subscribers who have opened the email once or more
clicked_unique:	The number of subscribers who have clicked on the email once or more
webversion_unique:	The number of subscribers who have requested the web version
accepted_ratio:	The ratio of accepted emails to the number of sent emails
opened_ratio:	The ratio of emails opened once or more to the number of accepted emails
clicked_ratio:	The ratio of emails that have been clicked once or more to the number of accepted emails

Example of 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
    }
}

Results of a campaign request

The results of a campaign.

Parameters

campaign_id (mandatory):

The ID of a campaign

Definition

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

Example of request

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

Example of response
{
    "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
    }
}

Viewing the results of all campaigns of an account

The results of all campaigns in an array of list objects. The report objects have been ordered in an array with the name 'data'.

Parameters

None.

Definition

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

Example of request

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

Example of response

{
    "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
	    }
	}
    ]
}