Looking for version 1.0?
We strongly recommend using version 2.0 of the API as it has more flexibility than version 1.0 and contains the most recent functionality. However, if you'd prefer to use the previous release, the SOAP-based version 1.0 is still available.
The API will allow you to interact with the Engagement Cloud system programmatically, automating many everyday tasks you might otherwise have to carry out. This is useful if you wish to increase your productivity within the Engagement Cloud system.
You can use the API to connect almost any system to Engagement Cloud. Provided your CRM, website or any back office system also has an API, then it 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 Engagement Cloud can be automated via the API.
To get started using our API, you will need to create an API user. These API user credentials (username/password) are required to authenticate each operation/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:
- Log in to Engagement Cloud
- Click the person-and-cog icon in the bottom left corner to produce the settings menu and select Access
- Click the API users tab (unless you're already in it)
- Click New user
- The username (email address) is automatically generated for you and must not be edited
- You can add a description to differentiate between API users, which is useful if you have multiple ones
- Enter a password and confirm it
- Select the Enabled checkbox is ticked
- Click Save
You will only be able to access the API using the API user credentials, although you can have more than one API user per Engagement Cloud account.
Please note: When creating API users, it's best practice to create one user per system (for instance, one for a Magento integration and another one for a Dynamics integration) and not share an API user for different integrations. This makes it easier to revoke individual API users should you need to, as well as isolate and diagnose problems with integrations.
Can't create an API user?
Only the owner of your account or admin users (users with the 'Can manage account' permission enabled) can add API users.
If you can't complete the process above, or if some of the options don't appear to you, then contact your account owner.
Engagement Cloud accounts belong to different regions, depending upon where they are based in the world. We 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.dotmailer.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.
When providing input you must ensure that the request is well-formed, paying attention to make sure that the XML or 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. When possible, we always recommend using an existing REST or SOAP wrapper/library which can take care of any complications for you.
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 GetServerTime operation/method 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.
We have a limit of 2000 API calls per 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 Engagement Cloud account. Under normal usage conditions, you should not reach this limit. GetServerTime requests, however, are not counted towards the calls you have made.
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).
To see how many calls you have made in the last hour period:
- Log into Engagement Cloud
- 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.
Click on [find out more] alongside 'API usage' to access the 'API usage logging' page. To access this, go to the left-hand side navigation panel and click the person-and-cog icon > Account, and then navigate to the 'API useage' area. Here, you will click '[find our more]', then 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.
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.0, 1.1, 1.2 and 1.3.
You can test 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/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]
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).
We have working code samples in C# for all REST operations and SOAP methods in the reference section. You can find these along with documentation for all operations and methods available under the REST and SOAP sections.
If you're looking for languages other than C#, then try checking out our community supported projects area at GitHub - https://github.com/dotmailer/community-supported-projects (and feel free to contribute yourself!)
Updated 9 days ago