This document describes the Symplify public API and how to get started trying it out. Readers are assumed to have some familiarity with Symplify's graphical interface.
The API uses the REST methodology. A brief overview of RESTful web services can be found here:
While you're looking into integration options, please also take a moment to read about our Event Hub, which is our preferred method for real time data updates.
Symplify uses Postman as a third-party library to document the REST API. You can preferably test using Postman or you can copy the resources to whatever environment your are using.
Please note that when testing, it is your live data you're working with so any updates you make will alter settings for other users of your account so use POST/PUT and DELETE with care.
All examples in this documentation is prepared so that you can use a Postman environment where some static parameters are predefined, these are:
Value: Your Symplify API token
Value: https://eu-proxy-\[x].symplifymail.com (learn more below)
Value: Your customer ID
Value: Your database ID
You can select your preferred language in the top.
Evolution of the API
We will strive to keep the API backward compatible. This applies to all API calls that are not explicitly marked as draft or FOR INTERNAL USE ONLY in the Swagger documentation. This means that:
- Resource URIs not will not change
- Names of data fields in message body requests and responses will not change
- Data fields in message body requests and responses will not be removed
- New optional fields in message body requests and responses may be added in the future. Integrating systems should take this account, particularly when consuming responses from the REST API.
- New resources will be added as new functionality is made publicly available
- If incompatible changes are required in existing resources, the old ones will still be left available, unless the conditions under 7 apply.
- In some very unusual cases, internal changes in the system may render existing resources obsolete or insufficient for the task they were originally intended. In these cases the original resource will be left in place, but will be modified to return the HTTP response code 410 (Gone), with a response body including information on the reason.
You must always include your customerId when calling a Symplify resource. Log in to Symplify and find your customer ID in the main menu bottom
For most resources there are five methods you can call; get all, get one, create one, update one and delete one The syntax is mostly the same for all resources so you should be able to pick up the general idea pretty quick.
The URI structure generally looks like this:
server: https://www<x>.carmamail.com where X is the number of your server
customerId: your customer ID.
resource: the resource you want to use
id: the ID (if any) of the item you want to add/update/get/delete.
All data supplied to and received from the REST API uses the application/json media type. To ensure full compatibility, please make sure that:
All GET requests include the header:
All PUT and POST request include the following headers:
All data sent to the API is expected to be in the standard application/json charset UTF-8, unless explicitly stated otherwise as a charset parameter in the Content-Type header. All data sent as responses from the API will be in the UTF-8 charset.
Types of Requests
To get all data you issue a GET request without id, e.g.
To get one data you issue a GET reqest with an id, e.g.
To create a new data you will issue a POST request without id. Usually creation of a new entity will require data for the entity to be included in the message body, e.g.:
<entity to create as JSON>
To update one data you issue a PUT request with id and the data required to be used for updating the entity:
<entity to update as JSON>
To delete you issue a DELETE request with an id, i.e.
You can test a request directly in the Swagger interface by entering your credentials, customer id and other data needed for the method.
For testing you can use the same credentials that you use to log into Symplify. For security reasons we recommend not using your own credentials in production. The recommendation for production is to get a special API user for your account and use these credentials. You can request an API user by sending an email to firstname.lastname@example.org.
GET requests are used to retrieve data from the system.
POST requests are used to create data in the system.
When issuing a POST you often have to supply a JSON formatted message body containing the data for the entity you are creating.
PUT requests are used for updating data in the database. The message body should include data required for updating the entity. For some resources you only need to specify the fields that you are changing, but usually you should make sure to include all fields as received from a previous GET request (the id, dateCreated and dateModified fields are not required. The Id field this is specified in the URI and the other are created/updated automatically).
To delete an entry you supply the customer id and the id of the data to be deleted.