FAQs

What is the API?

The Dotdigital API is a web service available in REST and is built and maintained by Dotdigital.

The API will allow you to interact with the Dotdigital system programmatically, and send messages via our Communications features.

Why should I use the API?

You can use the API to connect any system to Dotdigital. Your CRM, website, or 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 Dotdigital can be automated via the API.

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

Add real time omnichannel messaging to your systems using channels such as Transactional email, SMS, WhatsApp, Push and more...

How can I integrate with your API?

The API does require a developer to write the integration. Because it's a standardized technology, this should be relatively straightforward.

Do you support SOAP?

Yes, we have SOAP support for a good range of the API but our focus is on REST moving forwards. Any SOAP support will be maintained but we are not planning on expanding the functionality covered by SOAP in the API further. You can find the supported SOAP methods here.

How do I reset my username and password for my API user?

Log in to Dotdigital
Click on the more-options icon in the bottom left corner to produce the settings menu and select Access
Select the API users tab (unless you're already in it)
Click New user
Locate the API user that you need to reset the password for and click the Edit icon
Enter your new password in the ‘Password’ field
Confirm your new password in the ‘Confirm password’ field below
Check the 'Enabled' box is ticked
Click Save

Please note: You will only see Access in the settings menu if you're an account owner, or an admin user of an account (you have the 'Can manage account' permission enabled). If you can't see it, please contact your main account owner who'll either be able to give you the permission or follow the above steps to reset your API user's username and password for you.

How do I unlock an API user?

Your API user will become locked in either of the following circumstances:

You enter an invalid password for an API user five times
Your account is disabled

To unlock an API user, follow the steps to reset your password. You can either enter a new password or enter the old password if you remember it.

If your disabled account is re-enabled, you'll need to unlock your API user in the same way.

How can I enable an API managed login?

Log in to Dotdigital
Click on the person-and-cog icon in the bottom left corner to produce the settings menu and select Access from the menu
Select the API users tab (unless you're already in it)
Select New user
The username (email address) is automatically generated for your managed user and must not be edited
You can add a description to differentiate your managed API user
Enter a password and confirm it
Check the 'Enabled' box is ticked
Click Save

Please note: You will only see Access in the settings menu if you're an account owner, or an admin user of an account (you have the 'Can manage account' permission enabled). If you can't see it, please contact your account owner who'll either be able to give you the permission or follow the above steps to enable an API managed login for you.

How do I know the correct API endpoint to call for my account's region?

There are two ways:

Click on the person-and-cog icon in the bottom left corner to produce the settings menu, select Access and then, if you're not already in it, click on the API users tab. Here you'll find your API endpoint.
Call Get account information/GetCurrentAccountInfo using r1-api.dotmailer.com as the endpoint, and this will return your account's correct endpoint.

How do I integrate my CRM system with my account using an API connection?

We have several pre-built integrations, so check the Integration hub in the more-options menu, or with your account manager - you may not need to do any work yourself!

Assuming you do need to use the API, first you will need to make sure you have an account that allows API connection.

You will then need to set up an API user (see How can I enable an API managed login?).

Once this is done, you can then call the API methods from a web/windows application.

My API request limit is being reached. Can you tell me what requests are pushing me over the limit?

By default we don't store the requests that have been called, only the number of calls made to your account.

However, you can turn on API usage logging for 60 minutes if you wish. To do this:

Click on the person-and-cog icon in the bottom left corner to produce the settings menu and select Account
Click on [find out more] alongside 'API usage' to access the 'API usage logging' page
Click Begin logging API requests if you wish to turn on 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.

The common culprits of exceeding your limit are:

Operations/methods called in loops
Use of singular instead of bulk API methods such

My API call limit is being reached. Can you increase my API calls until I sort it out?

We cannot increase your API call limit, whilst you work to improve the efficiency of your application. We are able to offer some advice on how to help reduce the amount of calls you are making but this does not consist of writing code for you. 2000 calls per hour is generally considered a generous amount and you should be able to work comfortably within these limits.

Where can I see the amount of API calls I have made in an hour period?

Log in to 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

What constitutes an API request?

We define an API request as you calling a REST operation or SOAP method from our API. Each operation or method counts as an individual API call.

We do not have any methods or operations which count as more than one API call per call.

The Get server time/GetServerTime operation/method does not get added to your call total.

What are the limits for contact data fields?

Text: 255 characters, in UTF-8.
DateTime: any date between 1753-01-01 00:00:00 and 9999-12-31 23:59:59 UTC.
Numeric: positive or negative numbers between (-+)999999999999999999. You can also have 10 decimal places.

Why these limits?

We chose this as our best balance of high performance vs usefulness.

I sent a campaign but it has gone out at the wrong time?

The API runs on UTC. Please check your time zone and make sure any datetime values sent to the API are specified in UTC.

I can't call an API operation/method with my Dotdigital login?

Correct, you can only use a valid API user to call API methods/operations. Please see the API user setup steps for instructions on how to set up an API user.

Can I use the same API user credentials to log into another Dotdigital account?

No, each API user only corresponds to one Dotdigital account. You will need a different API user for each Dotdigital account you wish to connect to.

I can't log in to Dotdigital using my API user credentials?

Correct, you can only log into Dotdigital with a Dotdigital login. Your API user credentials can only be used to authenticate you when calling an API operation/method.

My developer has written some code which doesn't work properly. Can you fix it?

Whilst we can offer you guidance and assistance around errors that are occurring, it is the responsibility of your developers to build the application. If you are looking for developers with experience of using the API, please contact your account manager.

Will you help me review my code if I send it over?

We do not offer free coding support for the API, so whilst we are happy to help to an extent in optimising the amount of calls you are making, you will need to arrange for some development or consultancy with your account manager before we will work with and modify your code. Please also be aware that any information sent to us via email will not be sent securely and as such we would ask that you do not send us any sensitive information via email.

I think I have found a bug with operation/method X. What next?

Please let us know! Submit a ticket by email or through our support desk. The subject should be something descriptive of the problem such as "Operation/method x returns z instead of expected y". Please include as much detail as you can about the problem. The following information should be the minimum:

What operation/method are you calling?
What do you expect to happen?
What is actually happening?
Include any error messages that you have received
When did this last happen and has it always happened?
Please include any other information you feel might be relevant

I am unable to change the username for my API user?

That's correct - the username for your API user is automatically generated and cannot be changed.

Do you provide a secure API?

Yes - our API is available over TLS (v1.2 and 1.3) and uses SHA-256 certificates. Each operation/method called also requires your username and password to ensure the session is secure.

Triggers are not sending when I upload contacts to Dotdigital using the API?

Triggers such as a join action will not fire when contacts are added to an address book using a bulk upload method. Adding a single contact to an address book will cause the trigger to fire.

How can I get a list of contacts who have unsubscribed?

You can use the operation Get unsubscribed contacts since date which will return a list of unsubscribers after a given date.

What exceptions can be returned to me via the API?

Please see the Error response types section.

I keep getting this error - 'Server was unable to process request...' but the exception doesn't appear in your list of possible exceptions?

An error of this type means that there is something incorrect with the request you are sending to the API. Suggested steps would be to simplify the call and ensure that each of the parameters is valid by checking the REST/SOAP definition of that particular operation/method.

I have scheduled a campaign to be sent. How can I check the status of the campaign?

As long as you know the send ID of a campaign, you can use the operation Get campaign send status to query the status of a campaign.

What files can the API accept?

CSV and XLS files are the only files that can be uploaded via the API. We recommend that you use the CSV data format to ensure the highest data integrity. We also recommend CSV files are UTF-8 encoded to avoid any issues with unusual characters. Alternatively, if you choose to use a XLS format, please ensure that all the data is on the first work sheet.

Do you have any code samples that I can look at?

Our documentation for REST operations creates code samples for you based on your language selection and parameters. SOAP methods all contain samples for implementation in C#.

We also have this page of community contributed code on GitHub - https://github.com/dotmailer/community-supported-projects.

And, of course, please feel free contribute if you wish to.

The API isn't accepting the date format I am using. Why is this?

The API is a REST and SOAP based service and as such expects dates in ISO 8601 format .

How can I test the API?

You can test out our API's REST/SOAP operations/methods by using tools such as Chrome's Postman extension or SoapUI, amongst other possible options.

However, be warned - testing these operations out will 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 in mind, it's a good idea to sign up and use a free trial account for testing. Or make sure you have a specially created testing address book and test campaigns, etc., that you don't mind being directly affected by such 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 within the documentation. The API user credentials for the account is [email protected]/demo. Any data posted to the account doesn't persist.

We want to set up integration with Dotdigital and our CRM - are you available for a conference call to discuss this integration?

We would like to help you in every way possible. Please ensure the following before arranging a conference call with your account manager and one of our support technicians:

Your developers have read through all of the documentation on this site.
Your developers have provided a list of any questions they have that have not been covered on this site at least a day before the call

Please also be aware that we can only help in terms of specific errors that you encounter, and helping you to stay within your call limits. Our account managers and support team will not design the integration for you, implement said integration or review your code.

Do you support CORS

We do not support CORS as our APIs must only be used server side to avoid exposing your authentication details!