{"_id":"55dd9f4dab0e4d210045aaeb","version":{"_id":"55dd9f4dab0e4d210045aae9","__v":39,"project":"55dd9f2e0efd5821000d54d9","createdAt":"2015-08-26T11:13:17.024Z","releaseDate":"2015-08-26T11:13:17.024Z","categories":["55dd9f4dab0e4d210045aaea","55ddb5fa9067202b00ddff6f","55e0472c6bad670d0081f213","55e04764a44fae0d00214671","55e047a9a44fae0d00214672","55e047b258c5460d0076a9a7","55e95e337fc27b2d00d32cf2","55e979bda7ca823900ad549a","55edb8c18dcb210d0056900b","55f0365c8563861700a33765","55f03677d58f9b1900acf996","55f036938eeefc23001ea5de","55f036a38563861700a33767","55f036c08563861700a33769","55f036d02911b72100482cd7","55f036e92911b72100482cd9","55f036fa8563861700a3376b","55f0370ee507711900e58c69","55f0371df6101b1900c70700","55f0374f2911b72100482cdb","55f0375e2911b72100482cdc","560eb0f659cb8d0d0015cd52","560eb25239fad419002ae1e0","561fb64d4d67490d00804b2a","562b9f775a39cd0d009aff22","562ba0505a39cd0d009aff23","562ba149d56bc30d00f0cb18","562ba595f68a5f0d007b1f3b","562ba78fd56bc30d00f0cb1b","562ba8b95a39cd0d009aff27","562baadf6562140d001501d2","562bab37f68a5f0d007b1f3d","562bc1bf9ebc950d000f7523","562bc99ced4bea0d00c11dfa","562bd29c1b98640d00714520","562bd5875a39cd0d009aff60","562bdfabff2da50d002c0aaf","562be0bd5a39cd0d009aff75","57a0b476d8313e1900454439"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"2.0.0","version":"2"},"parentDoc":null,"user":"552e19365d4baa0d007835ff","__v":44,"category":{"_id":"55dd9f4dab0e4d210045aaea","pages":["55dd9f4dab0e4d210045aaeb","55e96008ffba3323004216ea","55e96030e5d0c623003ed885","55e97a097f564237001d5b80","56795de3ade8221700923d2c","56797b1584397c0d00fe13ea"],"version":"55dd9f4dab0e4d210045aae9","__v":6,"project":"55dd9f2e0efd5821000d54d9","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2015-08-26T11:12:47.544Z","from_sync":false,"order":0,"slug":"overview","title":"Overview"},"project":"55dd9f2e0efd5821000d54d9","updates":["569f47b800e24d0d0047aa01"],"next":{"pages":[],"description":""},"createdAt":"2015-08-26T11:12:48.342Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":0,"body":"The dotmailer API version 2.0 is a web service available in both [REST](/docs/about-our-rest-api) and [SOAP](/docs/about-our-soap-api). \n[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"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](https://api.dotmailer.com/api.asmx) is still available.\",\n  \"title\": \"Looking for version 1.0?\"\n}\n[/block]\n## What is the API?\n\nThe API will allow you to interact with the dotmailer 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 dotmailer system.\n\n## Why you might use the API\n\nYou can use the API to connect almost any system to dotmailer. 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 dotmailer can be automated via the API.\n\n## Setting up your API user\n\nTo 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:\n\n  * Login to dotmailer\n  * Click on the person-and-cog icon in the bottom left corner to produce the settings menu and select **Access** \n  * Select the **API users** tab (unless you're already in it) \n  * Click on **New user**\n  * The username (email address) is automatically generated for you and must not be edited\n  * You can add a description to differentiate between API users, which is useful if you have multiple ones\n  * Enter a password and confirm it\n  * Check the 'Enabled' box is ticked\n  * Click **Save**\n\nYou will only be able to access the API using the API user credentials, although you can have more than one API user per dotmailer account.\n\n**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.\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Can't create an API user?\",\n  \"body\": \"Only the owner of your account (or a user with the 'Can manage account' permission) can add API users.\\n\\nIf you can't complete the process above, or if some of the options don't appear to you, then contact your account owner.\"\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"danger\",\n  \"title\": \"Make sure you're using the correct API endpoint for your region\",\n  \"body\": \"dotmailer 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. \\n\\nThis is important as you will not be able to use an API endpoint belonging to a different region.\\n\\nIf you don't know your account's correct API endpoint, then you can find this out in a couple of ways:\\n\\n  * 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. \\n  * Via the API: Call [Get account information](doc:get-account-information)/[GetCurrentAccountInfo](doc: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.\"\n}\n[/block]\n## Input and output\n\n[REST](https://en.wikipedia.org/wiki/Representational_state_transfer) and [SOAP](https://en.wikipedia.org/wiki/SOAP) are both standardised technologies that take in XML or JSON requests, and return XML or JSON requests. \n\nWhen 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. \n\nThe WADL and WSDL for the API can be found at https://api.dotmailer.com/v2/help/wadl and https://api.dotmailer.com/v2/api.svc respectively.\n\nWhen 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.\n\n## Restrictions\n\nWe 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 dotmailer account. Under normal usage conditions, you should not reach this limit. GetServerTime requests, however, are not counted towards the calls you have made. \n\nWe do reserve the right to slow down the amount of calls made to the API if we detect unusual usage patterns. \n\nWe 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](https://developer.dotmailer.com/docs/getting-started-with-the-api#section-api-usage-logging) below).\n\nTo see how many calls you have made in the last hour period:\n\n  * Log into dotmailer\n  * Click on the person-and-cog icon in the bottom left corner to produce the settings menu and select **Account**\n \nUnder ‘API usage’ you can see the total calls out of 2000 made in the last hour.\n\n## API usage logging\n\nClick 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.\n\n## Secure access\n\nAll 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, and 1.2.\n\n## Testing\n\nYou can test our API's REST/SOAP operations/methods by using tools such as Chrome's Postman extension or SoapUI, amongst other possible options.\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"Warning\",\n  \"body\": \"**Testing these operations/methods out will of course have the effect of posting, updating and deleting data within your live account.** \\n\\nBefore testing, be sure this is something you're happy with.\"\n}\n[/block]\nWith 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.\n\nWhilst 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.\n\nAlternatively, 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 demo:::at:::apiconnector.com/demo. Any data posted to the account doesn't persist.\n\nIf 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).\n\n## Code samples\n\nWe have working code samples in C# for all REST operations and SOAP methods.\n\nYou can find these along with documentation for all operations and methods available under the [REST](http://developer.dotmailer.com/docs/about-our-rest-api) and [SOAP](http://developer.dotmailer.com/docs/about-our-soap-api) sections.\n\nIf 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!)","excerpt":"This page will help you get started with dotmailer API version 2.0. You'll be up and running in no time!","slug":"getting-started-with-the-api","type":"basic","title":"Getting started with the API"}

Getting started with the API

This page will help you get started with dotmailer API version 2.0. You'll be up and running in no time!

The dotmailer API version 2.0 is a web service available in both [REST](/docs/about-our-rest-api) and [SOAP](/docs/about-our-soap-api). [block:callout] { "type": "info", "body": "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](https://api.dotmailer.com/api.asmx) is still available.", "title": "Looking for version 1.0?" } [/block] ## What is the API? The API will allow you to interact with the dotmailer 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 dotmailer system. ## Why you might use the API You can use the API to connect almost any system to dotmailer. 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 dotmailer can be automated via the API. ## Setting up your API user 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: * Login to dotmailer * Click on the person-and-cog 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 on **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 * Check the 'Enabled' box 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 dotmailer 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. [block:callout] { "type": "info", "title": "Can't create an API user?", "body": "Only the owner of your account (or a user with the 'Can manage account' permission) can add API users.\n\nIf you can't complete the process above, or if some of the options don't appear to you, then contact your account owner." } [/block] [block:callout] { "type": "danger", "title": "Make sure you're using the correct API endpoint for your region", "body": "dotmailer 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. \n\nThis is important as you will not be able to use an API endpoint belonging to a different region.\n\nIf you don't know your account's correct API endpoint, then you can find this out in a couple of ways:\n\n * 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. \n * Via the API: Call [Get account information](doc:get-account-information)/[GetCurrentAccountInfo](doc: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." } [/block] ## Input and output [REST](https://en.wikipedia.org/wiki/Representational_state_transfer) and [SOAP](https://en.wikipedia.org/wiki/SOAP) are both standardised technologies that take in XML or JSON requests, and return XML or JSON requests. 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. The WADL and WSDL for the API can be found at https://api.dotmailer.com/v2/help/wadl and https://api.dotmailer.com/v2/api.svc respectively. 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. ## Restrictions 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 dotmailer 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](https://developer.dotmailer.com/docs/getting-started-with-the-api#section-api-usage-logging) below). To see how many calls you have made in the last hour period: * Log into dotmailer * 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. ## API usage logging 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. ## 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.0, 1.1, and 1.2. ## Testing 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. [block:callout] { "type": "warning", "title": "Warning", "body": "**Testing these operations/methods out will of course have the effect of posting, updating and deleting data within your live account.** \n\nBefore testing, be sure this is something you're happy with." } [/block] 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 demo@apiconnector.com/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 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). ## Code samples We have working code samples in C# for all REST operations and SOAP methods. You can find these along with documentation for all operations and methods available under the [REST](http://developer.dotmailer.com/docs/about-our-rest-api) and [SOAP](http://developer.dotmailer.com/docs/about-our-soap-api) 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!)