API FAQs

What is the API?

The API (Application Programming Interface) is a SOAP based web service built and maintained by dotMailer.

Why should I use the API?

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

How can I integrate with your API?

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

How do I reset my user name and password for my API key?

  • Login to dotMailer
  • Select "My account" in the top right corner
  • Select "Manage users" on the left hand menu
  • Select the API tab
  • Locate the API user that you need to reset the password for.
  • Enter your new password in the "Password" text box.
  • Confirm your new password in the "Confirm password" textbox.
  • Click "Save".

How can I enable an API managed login?

  • Login to dotMailer
  • Select "My account" in the top right corner
  • Select "Manage users" on the left hand menu
  • Select the API tab
  • Locate the API user to be enabled and click edit
  • Check the checkbox labelled "Enabled"
  • Click "Save"

My limit is being reached, can you tell me what calls are pushing me over the limit?

No, we do not store the methods that have been called only the number of calls made to your account. Common culprits of exceeding your limit are:

My 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. 15,000 calls per 24 hours (our v1 API limit) and 2,000 calls per 60 minutes (our v2 API limit) are generally considered a generous amount of calls and you should be able to work comfortably within these limits.

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

  • Login to dotMailer
  • Click "My account" in the top right hand corner
  • Click "Current month activity" in the left hand menu
  • At the bottom under API useage you should be able to see the total calls made for the month and total calls in the last 24 hours.

What constitutes an API call?

We define an API call as you calling a method from our API (http://api.dotmailer.com). Each method counts as an individual API call. We do not have any methods which count as more than one API call per call. The GetServerTime method does not get added to your call total.

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

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

I can't call an API method with my dotMailer login?

Correct, you can only use a valid API key to call API methods, please see the setup steps for instructions on how to setup an API key.

Can I use the same API key (credentials) to log into another dotMailer account?

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

I can't login to dotMailer using my API key?

Correct, you can only log into dotMailer with a dotMailer login. Your API key can only be used to authenticate you when calling an API method.

Can I consume your web service API using silverlight?

No. To consume a web service with silverlight the web service requires a crossdomainpolicy.xml and or a clientaccesspolicy.xml file. We do not have these files as this can pose a potential security risk. If you wish to consume our web service using silverlight we recommend you build your own web service which talks to our API; your webservice can then talk to your silverlight application.

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

Whilst we can offer your 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 method X

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 "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 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 key?

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

Do you provide a secure API?

Yes - our API is also available over SSL (please see: https://api.dotmailer.com) and uses an AES-128 bit certificate. Each method called also requires your username and password to ensure the session is secure.

Triggers not sending when I upload contacts to dotMailer 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 ListUnsubscribers which will return a list of unsubscribers after a given date. Only the email address of the contact will be returned.

What exceptions can be returned to me via the API?

Please see the errors 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 are valid by checking the SOAP definition of that particular method.

I have scheduled a campaign to be sent, how can I check the status of the campaign?

If you have sent a campaign using either SendCampaignToAddressBooksWithProgress or SendSplitTestCampaignToAddressBookWithProgress you can use GetCampaignSendProgress to query the status of the campaign. If you haven't used this but know the Id of the campaign you can use GetCampaign to also get the status of the campaign. Currently it is not possible to get the actual dateTime of the scheduled send.

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 be 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 are on the first work sheet.

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

Our API method documentation has samples for implementation in C#. We also have this page of community contributed code and a lively support forum.

The API isn't accepting the date format I am using, why is this?

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

Do you have a test system for the API?

Currently we do not have a test system for the API. You should assume that any calls made to the API will affect your live dotMailer account. Therefore we recommend setting up and using test campaigns and address books, before moving straight on to your live data. Please also be aware that the test address book is used for seed lists within the account, and you should set up another address book to test with.

You could alternatively register for a free demo account which you can use for testing purposes.

We want to set up integration with dotMailer 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 before arranging a conference call with your account manager and one of our support technicians that:

  • Your developers have read through this guide and taken a look at the API web service (http://api.dotmailer.com )
  • Your developers have provided a list of any questions they have that have not been covered in this guide 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.