FAQs

What is the API?

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

The API allows you to interact with the Dotdigital system programmatically, and send messages through 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 using the API.

You might find the API useful if you want 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.

You can also 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 requires a developer to write the integration. Because it's a standardied technology, this should be relatively straightforward.

Do you support SOAP?

We have SOAP support for a good range of the API, but our focus is on REST. 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.
Expand the User menu in the bottom left and go to Settings > Access > API users.
Find the API user that you need to reset the password for and select the Edit icon.
Enter your new password in the Password field.
Confirm your new password in the Confirm password field.
Check the Enabled radio button is selected.
Select SAVE.

Please note: To see Access in the settings menu you must be an account owner, or a user with the Can manage account permission enabled. If you can't see it, please contact your main account owner who can either give you the required 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 becomes 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 re-enter the old password if you remember it.

If your disabled account is re-enabled, you need to unlock your API user in the same way. Re-enabling an account does not automatically unlock that account’s API users.

How can I enable an API managed login?

Log in to Dotdigital.
Expand the User menu in the bottom left and go to Settings > Access > API users.
Find the API user that you need to enable and select the Edit icon.
Select the Enabled radio button.
Select SAVE

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

There are two ways:

Expand the User menu in the bottom left corner and go to Settings > Access > API users. Your API endpoint is displayed.
Call Get account information/GetCurrentAccountInfo using r1-api.dotmailer.com as the endpoint, and this will return your account's correct endpoint.

Please note: To see Access in the settings menu you must be an account owner, or a user with the Can manage account permission enabled. If you can't see it, you need to make the API call instead, or ask a user with sufficient permissions to check for you.

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

We have several pre-built integrations, so check the App directory in the Connect area of the platform, or with your Customer Success representative - 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 want to, as detailed here.

This records 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 while 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 we cannot write code for you.

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

See the call rate limits page.

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 request.

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.

Can I call an API operation/method with my Dotdigital login?

No, 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 need a different API user for each Dotdigital account you want to connect to.

Can I log in to Dotdigital using my API user credentials?

No, you can only log into Dotdigital with a Dotdigital managed user 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?

While 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 see our partners or contact your Customer Success representative to discuss.

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

We do not offer free coding support for the API, so while we are happy to help to an extent in optimising the amount of calls you are making, you need to arrange for some development or consultancy with your Customer Success representative before we can work with or modify your code. You must be aware that any information sent to us by email will not be sent securely and as such we would ask that you do not send us any sensitive information by 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 chat. 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

Am I able to change the username for my API user?

No, 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.

Why aren’t triggered campaign sends or enrolments working when I upload contacts to Dotdigital using the API?

Triggers such as a join action don't fire when contacts are added to a list using a bulk upload method. Adding a single contact to a list causes 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 returns 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. What does it mean?

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 an email campaign to be sent. How can I check the status of the campaign?

As long as you know the send ID of an email 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.

Feel free contribute if you want 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.

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 list 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 recommend making use of a free trial account. This ensures that all of your tests do not affect your live data. The trial account can then be extended by your Customer Success representative 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 Customer Success representative 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 Customer Success and Support team cannot design or implement the integration for you, 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.