Getting Started with the dotmailer API

The API (Application Programming Interface) is a SOAP based web service built and maintained by dotmailer.

What is the API?

The API interface will allow your developers to interact with the dotmailer system programmatically, automating many everyday tasks you might otherwise have to carry out. This is useful if you wish to increase your productivity in the dotmailer system.

Why you might use the API

You can use the API to connect any system to dotmailer. Your CRM, website, or any back office system can be quickly connected allowing you to keep your data easily in sync. Data can be imported and exported on a schedule, and most common tasks available in dotmailer can be automated via the API.

You might find the API useful if you wish to integrate your CRM or database with dotmailer to ensure that the information shared between the two systems is kept effortlessly up to date and in sync.

Setting up your API key

To get started using our API you will need an API key. This API key is required to authenticate each method call you make and to make sure you are connected to the correct account. Setting one up is easy and can be done using the steps below:

  • Login to dotmailer
  • Click "My Account" in the top right corner
  • Click "Manage users" in the left hand menu
  • Click the "API" tab
  • Click "Add account"
  • The Username (email address) is automatically generated for you and must not be edited.
  • Enter a password
  • Check the enabled box is ticked
  • Click save

You will only be able to access the API using the API key although you can have more than one API key per dotmailer account.

If you cannot complete this process or some of the options don't appear to you, please contact your main account holder who will be able to follow these steps to create your account for you. Please remember that not all dotmailer editions have the API available.

Authentication

We require that each method is authenticated with an API key consisting of a username formatted as an email address and a password set by yourself on creation of the API key.If you haven't created your API key please follow the steps above to do so.

Input and Output

We have both REST and SOAP APIs. When providing input you must ensure that the request is well-formed, paying attention to make sure that the xml request definition adheres to the required case sensitivity which can be different depending on the method you are calling. Please make sure to check the sample request and response for each method that you are going to call. When possible, we always recommend using an existing SOAP wrapper/library which can take care of any complications for you. The WSDL and WADL for the APIs can be found at http://api.dotmailer.com.

When you are using dateTime values in your method calls please be aware that our API runs on UTC (Coordinated Universal Time) and will return all dateTimes in UTC. To make sure that you are using the correct time you can use GetServerTime to get the current time of the server our API runs on. This ensures that any time dependent routines will run at the expected time.

Restrictions

We set a limit of 2,000 API calls in a 60 minute period, when this limit is reached we will prevent further API calls to be made to that dotmailer account. Under normal usage conditions, you should not reach this limit. This limit is reset every hour. We class each method call made with the exception of GetServerTime as one API call. We do reserve the right slow down the amount of calls made to the API if we detect unusual usage patterns and we do not store the actual API calls made to the account only the amount of calls made.

To see how many calls you have made in a 24 hour period:

  • Login to dotmailer
  • Select "My Account" in the top right corner
  • Select "Current month activity"
  • At the bottom under API usage you should be able to see the total calls made for the month and the total calls in the last 24 hours.

Secure access

All your API requests can be made via http or https. We recommend that you use https for all requests. Our SSL uses an AES-128 bit certificate.

Testing

Whilst you are developing and testing your integration with our API we encourage you to signup and use a free trial account. This will ensure that all of your tests will not affect your live data. The trial account can then be extended by your account manager for any required additional time.