Working with the API
Features
With the API 3.0, you have access to the following functionalities
- Mailings
- Send mailings from a zip file
- List mailings
- Get details of a single mailing
- Get mailing statistics
- Manage recipient lists
- Manage recipients
- Manage your blacklist
- Manage API users for your account
Getting access
To access the API you need a account. Then you need to create an API user. To do this, log into your account, and access the API user management interface via Settings › API.
Throttling
Our API is throttled by request volume. You can do a maximum of 10 requests per second. If you exceed your request limit, a Statuscode 503 response will be returned.
Accessing the API
Sending manual HTTP requests
The API 3.0 supports HTTP Basic Authentication. Please see the following example on how to use curl to make an authenticated request:
curl --request GET \
--url 'https://apiv3.emailsys.net/mailings' \
--user 'apiusername:apipassword'
Examples
Please check our github repository for a number of PHP code examples.
API structure
Our API uses a RESTful architecture throughout. Most of the API is self-describing (see HATEOAS) using HAL where appropriate.
Data format
Our API uses the JSON format. Accept and Content-Type headers should always be "application/json" unless specified otherwise in the respective services' documentation. Related links (e.g. for pagination) will be provided using HAL. Please see the following sample response for a paginated recipient list.
{
"_links": {
"self": {
"href": "https://apiv3.emailsys.net/recipients?recipientlist_id=1&page=1"
},
"first": {
"href": "https://apiv3.emailsys.net/recipients?recipientlist_id=1"
},
"last": {
"href": "https://apiv3.emailsys.net/recipients?recipientlist_id=1&page=1"
}
},
"_embedded": {
"recipients": [
{
"id": "1",
"email": "michael.j.fox@example.net",
"firstname": "Michael J.",
"lastname": "Fox",
"gender": "male",
"title": null,
"zip": "",
"birthdate": null,
"extra1": "testdata-extra1",
"extra2": "testdata-extra2",
"extra3": "testdata-extra3",
"extra4": "testdata-extra4",
"extra5": "testdata-extra5",
"extra6": "testdata-extra6",
"extra7": "",
"extra8": "",
"extra9": "",
"extra10": "i",
"mailtype": "html",
"foreign_id": null,
"created_ip": "127.0.0.1",
"created_host": null,
"created": "2018-01-01 12:52:45",
"updated": "2018-01-02 11:09:43",
"_links": {
"self": {
"href": "https://apiv3.emailsys.net/recipients/1"
}
}
}
}
}
}
SSL
Our API is HTTPS-Only, it is not possible to access it via HTTP. Please make sure your client library supports HTTPS.