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. hen using the reference docs you must ensure that 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 can not 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:

• In-app: Go to Settings ( ⋮ ) > Access and then select the API users tab. Your API endpoint is displayed at the top of the page. Only account owners or admin users (users with the Can manage account permission enabled) can view the Access area.

  📘

  New navigation

  If you are using the updated Dotdigital user interface, then to view your account's API endpoint:

  1. Expand the User menu in the bottom left and select Settings.
  2. Go to Access > API users.

• Using the API: Call Get account information/GetCurrentAccountInfo using r1-api.dotdigital.com as the endpoint (regardless of what region you're in), and this returns 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 can not 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.

Dates and times

When you are using date/time values in your operation or method calls, you must be aware that our API runs on UTC (Coordinated Universal Time) and returns all dates/times in UTC in ISO 8601 format. 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 run at the expected time.

Paging through data

🚧

The pagination mechanism differs between our v2 and v3 services. You must ensure you use the correct method for the call in use. Learn how to identify which API version a call uses here.

Where API calls have paging support the following paging mechanisms are used:

For v2 service calls

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

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 returns records 1 to 100. For subsequent calls 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.

For v3 service calls

We use the Seek Pagination (also referred to as Continuation Token or Cursor technique) for pagination with v3 service calls. This technique is simple to use as you only have to state a maximum number of data items to return per call, and optionally set a marker to indicate where the result set should start from.

Passing the pagination parameters

The parameters to control the pagination should be passed on the query string of the URI:

For the initial call to a service that supports pagination you would normally not pass any of the pagination parameters, as you are starting a new data set, and this call will return a set of pagination links which you can then subsequently use to move through the data set.

Pagination Links

Pagination links are helpful URI links and markers to retrieve related data pages when returning a page of data, such as the next page link, previous page link etc… These links can be used to navigate the data set, for API calls use the marker value to move through the data set when passed in the marker query string.

Pagination links are returned by service calls that support pagination as follows:

links object:

linkDetails object:

Example
In this example the limit is set to 2 and this is the returned response from the first page:
URI: https://api.dotdigital.com/accounts/v1?limit=2&~marketSector=eq::retail

{
  "_links": {
    "self": {
      "href": "https://api.dotdigital.com/accounts/v1/accountId/12456",
      "marker": "12456"
    },
    "first": {
      "href": "https://api.dotdigital.com/accounts/v1/accountId/12456",
      "marker": "12456"
    },
    "next": {
      "href": "https://api.dotdigital.com/accounts/v1/accountId/12456",
      "marker": "12458"
    }
  },
  "_items": [
    {
      "id": "12456",
      "name": "Acme corp.",
      "created": "2020-01-01T15:43:10Z",
      "updated": "2020-01-15T13:05:00Z",
      "marketSector": "retail",
      "users": "https://api.dotdigital.com/users/v1?12456"
    },
    {
      "id": "12457",
      "name": "Smith inc",
      "created": "2019-06-01T15:43:10Z",
      "updated": "2019-09-15T13:05:00Z",
      "marketSector": "retail",
      "users": "https://api.dotdigital.com/users/v1?12457"
    }
  ]
}

Error handling

🚧

The error reporting differs between our v2 and v3 services. You must ensure you use the correct method for the call in use. Learn how to identify which API version a call uses here.

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.

For v3 service calls

For API v3 calls we provide more error information in the form of a standard error response. The error response contains both machine readable version of the error as well as human readable (in American English) to ensure the errors can be reliably understood and handled by code as well as give good quality error feedback to the developer.

The error response data contract is:

error object:

For example:

Basic error:

{
  "errorCode": "accounts:maxAccountLimit",
  "description": "Maximum account limit reached!",
}

Using the details array:

{
  "errorCode": "contacts:invalidContacts",
  "description": "Invalid contact data",
  "details": [
    {
      "item": "email",
      "error": "You must specify a value"
    },
    {
      "item": "firstName",
      "error": "Cannot exceed 256 characters"
    }
  ]
}

Restrictions

API Rate limits

There is a call rate limit set per account of 2000 API calls per rolling hour (making a total of 48,000 calls over a 24 hour period). When this limit is reached we 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.

📘

Accounts opted-in to our unified contacts public preview are granted higher call rate limits; find out more here.

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 want to (see API usage logging below).

For the APIs that have call limits applied to them you can monitor the call limit usage. To do this:

1. Log into Dotdigital
2. Go to Settings ( ⋮ ) > Account.
   On the Account usage tab, under API usage, you can see the total calls out of 2000 made in the last hour.

📘

New navigation

If you are using the updated Dotdigital user interface, then to enable API logging:

1. Expand the User menu in the bottom left and select Settings.
2. Go to Access > API users.

API usage logging

You can enable API call logging to help diagnose issues or understand API usage patterns.

To do this:

1. Go to Settings ( ⋮ ) > Account.
2. On the Account usage tab, under API usage, select '[find out more]', then select BEGIN LOGGING API REQUESTS.

📘

New navigation

If you are using the updated Dotdigital user interface, then to enable API logging:

1. Expand the User menu in the bottom left and select Settings.
2. Go to General > Usage.
3. Under API usage, select '[find out more]', then select BEGIN LOGGING API REQUESTS.

Once enabled, API call logging is activated for 60 minutes. This records all authenticated API calls that API users make in the account. API calls that fail to log in, or contain invalid XML or JSON, are not 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 explore the possibility of a sandbox account for testing. You can speak to your Customer Success rep about this. Alternatively, make sure you have a specially created testing address books and test campaigns, and so on, that you don't mind being directly affected by test API calls.

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 do 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