API end points

The Dotdigital API is delivered across several API end points, but all are secured with the same API user credentials. Some of the end points are region specific, and others are global. Please ensure when using the reference docs that you ensure you use the correct end point.

Region specific end points

Dotdigital accounts belong to different regions, depending upon where they are based in the world. Some of our APIs require you to use the correct API endpoint for your region.

This is important as you will not be able to use an API endpoint belonging to a different region.

If you don't know your account's correct API endpoint, then you can find this out in a couple of ways:

• Via the app: Click on the person-and-cog icon in the bottom left corner of the application to produce the settings menu, select Access and then click on the API users tab. Here you'll find your API endpoint. Only account owners or admin users (users with the 'Can manage account' permission enabled) will have Access available though.
• Via the API: Call Get account information/GetCurrentAccountInfo using r1-api.dotdigital.com as the endpoint (regardless of what region you're in), and this will return your account's correct endpoint.

The regions are:

🚧

Make sure you're using the correct regional API endpoint for your account

This is important as you will not be able to use an API endpoint belonging to a different region, and instead will receive a 403 - Forbidden: Access is denied error. See above for details of now to find your accounts region.

🚧

We will only accept connections using TLS 1.2

For security reasons we do not accept SSL connections negotiated using TLS 1.0-1.1 anymore, and almost all OS's support TLS 1.2.

If you are using .Net this is usually done automatically for you, but on versions of .Net prior to 4.6 TLS 1.2 is supported but is not the default protocol, and needs to be set explicitly.

ServicePointManager.SecurityProtocol = (SecurityProtocolType)3072;

See this article for more information.

Input and output

REST is a standardized technology that uses JSON to pass structured requests and responses and the HTTP protocol to invoke and select methods.

When providing input you must ensure that the request is well-formed, paying attention to make sure that the JSON request definition adheres to the required case sensitivity which can be different depending on the method or operation you are calling. Please make sure to check, where provided, the sample request and response for each method or operation that you are going to call.

The WADL for the API can be found at https://api.dotdigital.com/v2/help/wadl

Dates and times

When you are using date/time values in your operation or method calls please be aware that our API runs on UTC (Coordinated Universal Time) and will return all date/times in UTC. To make sure that you are using the correct time you can use the Get server time operation 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.

Paging through data

Where API calls have paging support the following paging mechanism is used.

Each call to the API method can return up to 1000 records, the number of records to fetch is specified by the Select parameters.

To iterate through the record set you use the Select and Skip parameters in tandem. The Skip parameter allows you to specify an offset into the record set. If you want to iterate through the record set by 100 records at at time you should set the Select parameter to 100 and the Skip parameter to 0, which will return records 1 to 100. For subsequent call you should increment the Skip parameter by your Select parameter value (100) and continue to call until 0 or less than the Select parameter records are returned as this indicates the end of the record set.

Error handling

With the Dotdigital API, you can expect conventional HTTP response codes to indicate the success or failure of an API request.

Typically, HTTP response codes mean:

• 200 range - a successful request
• 400 range - a failed request (a request parameter wasn't included, an object couldn't be found, etc.)
• 500 range - an error with our servers (these will be rare)

400 range HTTP response codes indicating a failed request come with an error response type in the body of the response.

Restrictions

API Rate limits

The following APIs have a call limit of 2000 API calls per rolling hour for an account (making a total of 48,000 calls over a 24 hour period). When this limit is reached we will prevent further API requests to that Dotdigital account, and return a HTTP 400 response with the following message:

Your account has generated excess API activity and is being temporarily capped. Please contact support. ERROR_APIUSAGE_EXCEEDED

Under normal usage conditions, you should not reach this limit, if you are hitting the limits please ensure you are batching your data changes and using our bulk API calls.

Please note: Certain calls are exempt from the call restrictions as we understand they will require frequent calling such as polling status checks, or are of critical importance such as updating the opt out status of a contact or sending an SMS or transactional email. Calls that are exempt will have this stated in their reference documentation, otherwise assume the call limits apply.

We do reserve the right to slow down the amount of calls made to the API if we detect unusual usage patterns.

We do not, by default, store the actual API calls made to the account, only the amount of calls made. However, you can turn on API usage logging for 60 minutes if you wish (see API usage logging below).

For the APIs that have call limits applied to them you can monitor the call limit usage by:

• Log into Dotdigital
• Click on the person-and-cog icon in the bottom left corner to produce the settings menu and select Account

Under ‘API usage’ you can see the total calls out of 2000 made in the last hour.

API usage logging

To enable API calls logging to help diagnose issues or understand API usage patterns do the following:

• Go to the left-hand side navigation panel and click the . . . > Account menu option
• look for the 'API usage' area towards the middle
• Click the '[find our more]', then click Begin logging API requests

Once clicked it will turn on API call logging for 60 minutes. This will record all authenticated API calls that API users make in this account. API calls that fail to log in, or contain invalid XML or JSON, will not be logged.

Secure access

All your API requests can be made via HTTP or HTTPS. For security reasons, we would however strongly recommend that you use HTTPS for all requests. Our servers use SHA-256 certificates and support TLS v1.2 and 1.3.

Testing

You can test our API's by using tools such as Chrome's Postman extension or Postman desktop, amongst other possible options.

🚧

Warning

Testing these operations/methods out will of course have the effect of posting, updating and deleting data within your live account.

Before testing, be sure this is something you're happy with.

With the above warning in mind, it's a good idea to sign up and use a free trial account for testing. Alternatively, make sure you have a specially created testing address book and test campaigns, etc., that you don't mind being directly affected by test API calls.

Whilst you are developing and testing your integration with our API, we would certainly recommend making use of 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.

Alternatively, you can use our dummy account, which returns dummy data, to test the majority of our REST operations and SOAP methods. The API user credentials for the account are:

Username: [email protected]
Password: demo

Any data posted to the account doesn't persist.

If using the dummy account, please expect to encounter some restrictions and limitations. You won't be able to test all operations and methods, nor will those that can be tested necessarily return all of the data you might expect when using a normal account (for example, Get account information/GetCurrentAccountInfo won't return an API endpoint).

Code samples

Under of reference section the documentation provides basic code samples to make the API call you are looking at, but more comprehensive examples can be found:

• In the Recipes section
• Examples for the omnichannel API in Github here.
• Try checking out our community supported projects area at GitHub - https://github.com/dotmailer/community-supported-projects (and feel free to contribute yourself!)

Next steps

Discover what you can do with our powerful APIs in the reference sections below:

• Quick starts
• Accounts and utilities
• Contacts and data
• Marketing and automation
• Communications