DOTGO Reseller API Reference Guide
CMRL Version 1.0
1. Introduction
The DOTGO Reseller API provides powerful capabilities for integrating DOTGO text messaging services into existing web sites, content management systems, and customer relationship management systems and for developing your own web-based tools for using DOTGO.
This document describes the DOTGO Reseller API. The document assumes that you have some familiarity with DOTGO (obtained, e.g., by reading A Brief Introduction to DOTGO), the DOTGO Developer Programs obtained, e.g., by reading DOTGO for Developers), and integration with the DOTGO Reseller Program (obtained, e.g., by reading DOTGO Reseller Integration Guide).
2. Authentication
In order to use the DOTGO Reseller API, you will need (1) a DOTGO Reseller API key and (2) a DOTGO API password. To obtain your DOTGO API key and password, please contact reseller@dotgo.com. Your API key and API password must be included with all calls to the API.
3. Request Format
The DOTGO Reseller API currently supports only REST request format. You can access the DOTGO Reseller API by making an HTTP GET or POST request (as appropriate) to
https://dotgo.com/api/1.0/
On each call to the DOTGO Reseller API, you must specify (1) your DOTGO API key, (2) your DOTGO API password, (3) a method parameter, and (4) various other method-specific parameters. The various methods and parameters are described in Appendix A.
4. Response Format
The DOTGO Reseller API currently supports only XML response format. The various method-specific blocks of XML are described in Appendix A, and the various data types are described in Appendix B.
A successful call to the DOTGO Reseller API returns XML with the following format, where [xml_block] is a method-specific block of XML.
<?xml version="1.0" encoding="UTF-8"?> <result success="1"> [xml_block] </result>
An unsuccessful call to the DOTGO Reseller API returns XML with the following format, where [error_code] is a numerical designation of the error and [error_description] is a text description of the error. The various numerical designations and text descriptions of the errors are described in Appendix C.
<?xml version="1.0" encoding="UTF-8"?>
<result success="0">
<error>
<code>[error_code]</code>
<description>[error_description]</description>
</error>
</result>
5. URLs and Subaccounts
Many DOTGO products and services are tied to URLs. For example, interactive and broadcast services operate with respect to URLs, and messaging plans and other products are purchased on a per-URL basis.
DOTGO allows the creation of arbitrary subaccounts within an account, which are used to group and organize URLs. For example, a DOTGO reseller may create a subaccount for each of its clients and add the URLs of each client to the respective subaccount.
URLs are added with the addURL method, and subaccounts are created with the createSubaccount method. A URL may be added without reference to a subaccount, in which case it is associated with the account with no subaccount.
URLs need not be be unique across subaccounts; in other words, a particular URL may be added to two or more subaccounts. (Of course, only one of these URLs may be active at any given time.) Accordingly, both URL and subaccount (which may be empty or null) must be specified in any method that targets a URL.
6. Times and Dates
The DOTGO Reseller API communicates times and dates via Unix time, which is defined as the number of seconds since midnight UTC of January 1, 1970 (which is known as the “epoch”), ignoring leap seconds. Various utilites are available to convert times and dates to and from Unix time.
7. Rate Limiting
Usage of the DOTGO Reseller API is subject to a rate limit of 100 requests over any five-minute interval. The limit is based on on a moving window that tracks the number of API requests made over the past five minutes (300 seconds). If an application exceeds this limit, then a descriptive error response is returned.
8. Summary
The DOTGO Reseller API provides powerful capabilities for integrating DOTGO text messaging services. The next step is to try it yourself!
Appendix A. Method Reference
This appendix describes all methods available through the DOTGO Reseller API. Each method is presented with its access, required and optional parameters, response, example invocation and response, and related methods. Methods are presented alphabetically, and a list of methods organized by category is presented in Appendix A.1.
A.1. List of Methods by Category
Application Method
Message Methods
Service Methods
Subaccount Methods
URL Methods
User Management Methods
A.2. addService
Description
Add service to URL of an account or subaccount. Note: A call to this method may trigger a billing event.
Access
This method must be accessed via an HTTP POST request.
Parameters
| Name | Description |
| subaccount (optional) | Subaccount containing URL for which service is to be added. If subaccount is not specified, then service is added for account with no subaccount. |
| url (optional) | URL for which service is to be added. |
|
service |
Service to be added.
|
|
serviceLevel |
Service level of service to be added. |
Response
This method provides no method-specific response.
Example Invocation
URL encode the following parameters and POST to https://dotgo.com/api/1.0/:
apiKey=abcdefghijklmnopqrstuvwxy
apiPassword=asdfghjkl
method=addService
url=http://site.com/index.cmrl
service=messaging
serviceLevel=2
Example Response
Content-Type: text/xml; charset=UTF-8 <?xml version="1.0" encoding="UTF-8"?> <result success="1"></result>
A.3. addURL
Description
Add URL to an account or subaccount.
Access
This method must be accessed via an HTTP POST request.
Parameters
| Name | Description |
| subaccount (optional) | Subaccount to which URL is to be added. If subaccount is not specified, then URL is added to account with no subaccount. |
| url | URL to be added. |
Response
This method provides no method-specific response.
Example Invocation
URL encode the following parameters and POST to https://dotgo.com/api/1.0/:
apiKey=abcdefghijklmnopqrstuvwxy
apiPassword=asdfghjkl
method=addURL
url=http://site.com/index.cmrl
Example Response
Content-Type: text/xml; charset=UTF-8 <?xml version="1.0" encoding="UTF-8"?> <result success="1"></result>
A.4. broadcastMessage
Description
Broadcast message (to followers of a match) from URL of an account or subaccount.
Access
This method must be accessed via an HTTP POST request.
Parameters
| Name | Description |
| subaccount (optional) | Subaccount containing URL from which message is to be sent. If subaccount is not specified, then message is sent from account with no subaccount. |
| url | URL from which message is to be sent. |
| pathTo | Path to which message is to be sent. |
|
channel(optional) |
Channel through which broadcast message is to be broadcast.
(Default: 368266.) |
| node | Node to be sent. (Note that node must be a valid CMRL <message> node.) |
| sendTime (optional) | Time at which message is to be sent. (Default: send immediately.) |
Response
A successful call to the broadcastMessage method returns a response element containing the following elements:
| Name | Description |
|
message |
Message that was broadcast.
(Note that message is a string that uniquely identifies the message that
was broadcast.) |
Example Invocation
URL encode the following parameters and POST to https://dotgo.com/api/1.0/:
apiKey=abcdefghijklmnopqrstuvwxy
apiPassword=asdfghjkl
method=broadcastMessage
url=http://site.com/index.cmrl
pathTo=newsletter
node=<message><content>Hello World</content></message>
channel=368266
Example Response
Content-Type: text/xml; charset=UTF-8 <?xml version="1.0" encoding="UTF-8"?> <result success="1"> <messsage>A123-B456</messsage> </result>
A.5. cancelMessage
Description
Cancel a queued message.
Access
This method must be accessed via an HTTP POST request.
Parameters
| Name | Description |
| message | Message to be canceled. |
Response
This method provides no method-specific response.
Example Invocation
URL encode the following parameters and POST to https://dotgo.com/api/1.0/:
apiKey=abcdefghijklmnopqrstuvwxy
apiPassword=asdfghjkl
method=cancelMessage
message=A123-B456
Example Response
Content-Type: text/xml; charset=UTF-8 <?xml version="1.0" encoding="UTF-8"?> <result success="1"></result>
A.6. createSubaccount
Description
Create a new subaccount.
Access
This method must be accessed via an HTTP POST request.
Parameters
| Name | Description |
| subaccount | Subaccount to be created. |
Response
This method provides no method-specific response.
Example Invocation
URL encode the following parameters and POST to https://dotgo.com/api/1.0/:
apiKey=abcdefghijklmnopqrstuvwxy
apiPassword=asdfghjkl
method=createSubaccount
subaccount=clientA
Example Response
Content-Type: text/xml; charset=UTF-8 <?xml version="1.0" encoding="UTF-8"?> <result success="1"></result>
A.7. deleteService
Description
Delete service from URL of an account or subaccount.
Access
This method must be accessed via an HTTP POST request.
Parameters
| Name | Description |
| subaccount (optional) | Subaccount containing URL from which service is to be deleted. If subaccount is not specified, then service is deleted from account with no subaccount. |
| url (optional) | URL from which service is to be deleted. |
|
service |
Service to be deleted.
|
| now | Flag indicating when service is to be terminated. If now is set to “1,” then service is terminated immediately; otherwise, service is terminated just before next billing cycle. (Default: 0.) |
Response
This method provides no method-specific response.
Example Invocation
URL encode the following parameters and POST to https://dotgo.com/api/1.0/:
apiKey=abcdefghijklmnopqrstuvwxy
apiPassword=asdfghjkl
method=deleteService
url=http://mywebsite.com/index.cmrl
service=messaging
now=0
Example Response
Content-Type: text/xml; charset=UTF-8 <?xml version="1.0" encoding="UTF-8"?> <result success="1"></result>
A.8. deleteURL
Description
Delete URL from an account or subaccount. Note: Deleting a URL from an account or subaccount will delete all services enabled for the URL.
Access
This method must be accessed via an HTTP POST request.
Parameters
| Name | Description |
| subaccount (optional) | Subaccount from which URL is to be deleted. If subaccount is not specified, then URL is deleted from account with no subaccount. |
| url | URL to be deleted. |
Response
This method provides no method-specific response.
Example Invocation
URL encode the following parameters and POST to https://dotgo.com/api/1.0/:
apiKey=abcdefghijklmnopqrstuvwxy
apiPassword=asdfghjkl
method=deleteURL
url=http://mywebsite.com/index.cmrl
Example Response
Content-Type: text/xml; charset=UTF-8 <?xml version="1.0" encoding="UTF-8"?> <result success="1"></result>
A.9. describeFollowedPaths
Description
Describe followed paths of URLs of an account or subaccounts.
Access
This method may be accessed via an HTTP GET or POST request.
Parameters
| Name | Description |
| subaccounts (optional) | Subaccounts containing URLs for which followed paths are to be described. May be set to “” (i.e. the empty string) to indicate account with no subaccount, a comma-separated list of subaccounts, or “*” to indicate the account and all subacounts. (Default: empty string.) |
| urls (optional) | URLs for which followed paths are to be described. May be set to a comma-separated list of URLs or “*” to indicate all URLs. (Default: *.) |
| followedPaths (optional) | Followed paths to be described. May be set to a comma-separated list of followed paths or to “*” to indicate all followed paths. (Default: *.) |
| limit (optional) | Limit to number of results to be returned. (Maximum: 500, default: 100.) |
| offset (optional) | Offset of results to be returned. (Default: 0.) |
Response
A successful call to the describeFollowedPaths method returns a response element containing the following element:
| Name | Description |
|
followedPaths |
Information
about followed paths. |
Example Invocation
URL encode the following parameters and GET or POST to https://dotgo.com/api/1.0/:
apiKey=abcdefghijklmnopqrstuvwxy
apiPassword=asdfghjkl
method=describeFollowedPaths
subaccounts=*
urls=*
followedPaths=newsletter,coupons
offset=0
limit=2
Example Response
Content-Type: text/xml; charset=UTF-8
<?xml version="1.0" encoding="UTF-8"?>
<result success="1">
<followedPaths count="20" displayed="2" offset="0">
<item followedPath="newsletter" subaccount="" url="http://site.com/index.cmrl">
<numFollowers>40</numFollowers>
</item>
<item followedPath="coupons" subaccount="clientA" url="http://siteA.com/index.cmrl">
<numFollowers>50</numFollowers>
</item>
</followedPaths>
</result>
A.10. describeFollows
Description
Describe relationships between paths that are being followed and registered paths that are following them.
Access
This method may be accessed via an HTTP GET or POST request.
Parameters
| Name | Description |
| subaccounts (optional) | Subaccounts containing URLs for which follows are to be described. May be set to “” (i.e. the empty string) to indicate account with no subaccount, a comma-separated list of subaccounts, or “*” to indicate the account and all subacounts. (Default: empty string.) |
| urls (optional) | URLs for which follows are to be described. May be set to a comma-separated list of URLs or “*” to indicate all URLs. (Default: *.) |
| followedPaths(optional) | Followed paths to be described. May be set to a comma-separated list of followed paths or to “*” to indicate all followed paths. (Default: *.) |
| followerPaths(optional) | Follower paths to be described. May be set to a comma-separated list of follower paths or to “*” to indicate all follower paths. (Default: *.) |
| limit (optional) | Limit to number of results to be returned. (Maximum: 500, default: 100.) |
| offset (optional) | Offset of results to be returned. (Default: 0.) |
Response
A successful call to the describeFollows method returns a response element containing the following element:
| Name | Description |
|
followType |
Information about
follows. |
Example Invocation
URL encode the following parameters and GET or POST to https://dotgo.com/api/1.0/:
apiKey=abcdefghijklmnopqrstuvwxy
apiPassword=asdfghjkl
method=describeFollows
subaccounts=clientA
urls=http://siteA.com/index.cmrl
followedPaths=coupons
followerPaths=jane@,john@
Example Response
Content-Type: text/xml; charset=UTF-8
<?xml version="1.0" encoding="UTF-8"?>
<result success="1">
<followings count="2" displayed="2" offset="0">
<item followedPath="coupons" followerPath="jane@" subaccount="clientA"
url="http://siteA.com.com/index.cmrl"></item>
<item followedPath="coupons" followerPath="john@" subaccount="clientA"
url="http://siteA.com.com/index.cmrl"></item>
</followings>
</result>
A.11. describeMessages
Description
Describe messages of URLs of an account or subaccounts.
Access
This method may be accessed via an HTTP GET or POST request.
Parameters
| Name | Description |
| subaccounts (optional) | Subaccounts containing URLs for which messages are to be described. May be set to “” (i.e. the empty string) to indicate account with no subaccount, a comma-separated list of subaccounts, or “*” to indicate the account and all subacounts. (Default: empty string.) |
| urls (optional) | URLs for which messages are to be described. May be set to a comma-separated list of URLs or “*” to indicate all URLs. (Default: *.) |
| messages(optional) | Messages to be described. May be set to a comma-separated list of messages or to “*” to indicate all messages. (Default: *.) |
| limit (optional) | Limit to number of results to be returned. (Maximum: 500, default: 100.) |
| offset (optional) | Offset of results to be returned. (Default: 0.) |
Response
A successful call to the describeMessages method returns a response element containing the following element:
| Name | Description |
|
messages |
Information about
messages. |
Example Invocation
URL encode the following parameters and GET or POST to https://dotgo.com/api/1.0/:
apiKey=abcdefghijklmnopqrstuvwxy
apiPassword=asdfghjkl
method=describeMessages
subaccounts=*
urls=*
messages=*
limit=2
offset=0
Example Response
Content-Type: text/xml; charset=UTF-8
<?xml version="1.0" encoding="UTF-8"?>
<result success="1">
<messages count="18" displayed="2" offset="0">
<item message="ABCD-EFGHI" subaccount="clientA" url="http://siteA.com/index.cmrl">
<channel>368266</channel>
<messageStatus>pending</messageStatus>
<pathTo>newsletter+</pathTo>
<node><![CDATA[<message><content>Hello World.</content></message>]]></node>
<timeCreated>1306164752</timeCreated>
<timeStart>1337787085</timeStart>
<timeStop></timeStop>
</item>
<item message="1234-56789" subaccount="clientB" url="http://siteB.com/index.cmrl">
<channel>368266</channel>
<messageStatus>complete</messageStatus>
<pathTo>JaneDoe</pathTo>
<node><![CDATA[<message><content>Hello Jane.</content></message>]]></node>
<timeCreated>1306166171</timeCreated>
<timeStart>1306166171</timeStart>
<timeStop>1306166171</timeStop>
</item>
</messages>
</result>
A.12. describeRegisteredPaths
Description
Describe registered paths of URLs of an account or subaccounts.
Access
This method may be accessed via an HTTP GET or POST request.
Parameters
| Name | Description |
| subaccounts (optional) | Subaccounts containing URLs for which registered paths are to be described. May be set to “” (i.e. the empty string) to indicate account with no subaccount, a comma-separated list of subaccounts, or “*” to indicate the account and all subacounts. (Default: empty string.) |
| urls (optional) | URLs for which registered paths are to be described. May be set to a comma-separated list of URLs or “*” to indicate all URLs. (Default: *.) |
| registeredPaths (optional) | Registered paths to be described. May be set to a comma-separated list of followed paths or to “*” to indicate all registered paths. (Default: *.) |
| limit (optional) | Limit to number of results to be returned. (Maximum: 500, default: 100.) |
| offset (optional) | Offset of results to be returned. (Default: 0.) |
Response
A successful call to the describeRegisteredPaths method returns a response element containing the following element:
| Name | Description |
|
registeredPaths |
Information
about registered paths. |
Example Invocation
URL encode the following parameters and GET or POST to https://dotgo.com/api/1.0/:
apiKey=abcdefghijklmnopqrstuvwxy
apiPassword=asdfghjkl
method=describeRegisteredPaths
subaccounts=clientA
urls=http://siteA.com/index.cmrl
pathsRegistered=*
limit=1
offset=0
Example Response
Content-Type: text/xml; charset=UTF-8
<?xml version="1.0" encoding="UTF-8"?>
<result success="1">
<registrations count="3500" displayed="1" offset="0">
<item registeredPath="anon-uezqy@" subaccount="clientA" url="http://siteA.com/index.cmrl">
<registrationTime>1305924403</registrationTime>
</item>
</registrations>
</result>
A.13. describeServices
Description
Describe services of URLs of an account or subaccounts.
Access
This method may be accessed via an HTTP GET or POST request.
Parameters
| Name | Description |
| subaccounts (optional) | Subaccounts containing URLs for which services are to be described. May be set to “” (i.e. the empty string) to indicate account with no subaccount, a comma-separated list of subaccounts, or “*” to indicate the account and all subacounts. (Default: empty string.) |
| urls (optional) | URLs for which services are to be described. May be set to a comma-separated list of URLs or “*” to indicate all URLs. (Default: *.) |
| limit (optional) | Limit to number of results to be returned. (Maximum: 500, default: 100.) |
| offset (optional) | Offset of results to be returned. (Default: 0.) |
Response
A successful call to the describeServices method returns a response element containing the following element:
| Name | Description |
|
services |
Information about services. |
Example Invocation
URL encode the following parameters and GET or POST to https://dotgo.com/api/1.0/:
apiKey=abcdefghijklmnopqrstuvwxy
apiPassword=asdfghjkl
method=describeServices
subaccounts=clientA,clientB
Example Response
Content-Type: text/xml; charset=UTF-8
<?xml version="1.0" encoding="UTF-8"?>
<result success="1">
<services count="3" displayed="3" offset="0">
<item service="messaging" subaccount="clientA" url="http://siteA.com/index.cmrl">
<billingPeriod>monthly</billingPeriod>
<coupon></coupon>
<discount>0.5</discount>
<initialCost>9.99</initialCost>
<lastBilledTime>1303941112</lastBilledTime>
<nextBilledTime>1307345103</nextBilledTime>
<renew>1</renew>
<serviceDetails>
<creditsExpireTime>1310046199</creditsExpireTime>
<creditsRemaining>10000</creditsRemaining>
<creditsTotal>10000</creditsTotal>
<creditsUsed>0</creditsUsed>
</serviceDetails>
<serviceLevel>1</serviceLevel>
<serviceStatus>active</serviceStatus>
</item>
<item service="messaging" subaccount="clientB" url="http://siteB.com/index.cmrl">
<billingPeriod>monthly</billingPeriod>
<coupon></coupon>
<discount>0.5</discount>
<initialCost>49.99</initialCost>
<lastBilledTime>1307454197</lastBilledTime>
<nextBilledTime>1310046197</nextBilledTime>
<renew>1</renew>
<serviceDetails>
<creditsExpireTime>1310043000</creditsExpireTime>
<creditsRemaining>27</creditsRemaining>
<creditsTotal>100</creditsTotal>
<creditsUsed>63</creditsUsed>
</serviceDetails>
<serviceLevel>2</serviceLevel>
<serviceStatus>active</serviceStatus>
</item>
</services>
</result>
A.14. describeSubaccounts
Description
Describe subaccounts of an account.
Access
This method may be accessed via an HTTP GET or POST request.
Parameters
| Name | Description |
| subaccounts (optional) | Subaccounts to be described. May be set to “” (i.e. the empty string) to indicate account with no subaccount, a comma-separated list of subaccounts, or “*” to indicate the account and all subacounts. (Default: empty string.) |
| limit (optional) | Limit to number of results to be returned. (Maximum: 500, default: 100.) |
| offset (optional) | Offset of results to be returned. (Default: 0.) |
Response
A successful call to the describeSubaccounts method returns a response element containing the following element:
| Name | Description |
|
subaccounts |
Information about
subaccounts. |
Example Invocation
URL encode the following parameters and GET or POST to https://dotgo.com/api/1.0/:
apiKey=abcdefghijklmnopqrstuvwxy
apiPassword=asdfghjkl
method=describeSubaccounts
subaccounts=clientA,clientB
Example Response
Content-Type: text/xml; charset=UTF-8
<?xml version="1.0" encoding="UTF-8"?>
<result success="1">
<subaccounts count="2" displayed="2" offset="0">
<item subaccount="clientA">
<premiumCount>2</premiumCount>
<urlCount>2</urlCount>
</item>
<item subaccount="clientB">
<premiumCount>8</premiumCount>
<urlCount>8</urlCount>
</item>
</subaccounts>
</result>
A.15. describeURLs
Description
Describe URLs of an account or subaccounts.
Access
This method may be accessed via an HTTP GET or POST request.
Parameters
| Name | Description |
| subaccounts (optional) | Subaccounts containging URLs which are to be described. May be set to “” (i.e. the empty string) to indicate account with no subaccount, a comma-separated list of subaccounts, or “*” to indicate the account and all subacounts. (Default: empty string.) |
| urls (optional) | URLs to be described. May be set to a comma-separated list of URLs or “*” to indicate all URLs. (Default: *.) |
| limit (optional) | Limit to number of results to be returned. (Maximum: 500, default: 100.) |
| offset (optional) | Offset of results to be returned. (Default: 0.) |
Response
A successful call to the describeURLs method returns a response element containing the following element:
| Name | Description |
|
urls |
Information about URLs.
|
Example Invocation
URL encode the following parameters and GET or POST to https://dotgo.com/api/1.0/:
apiKey=abcdefghijklmnopqrstuvwxy
apiPassword=asdfghjkl
method=describeURLs
subaccounts=*
urls=*
limit=2
Example Response
Content-Type: text/xml; charset=UTF-8
<?xml version="1.0" encoding="UTF-8"?>
<result success="1">
<urls count="3" displayed="2" offset="0">
<item subaccount="clientA" url="http://siteA.com/index.cmrl">
<cmrlCreatedTime>1303920078</cmrlCreatedTime>
<cmrlHosted>remote</cmrlHosted>
<cmrlModifiedTime>1307454017</cmrlModifiedTime>
<cmrlSize>123</cmrlSize>
<urlKey>wwww-xxxx-yyyy-zzzz</urlKey>
</item>
<item subaccount="clientB" url="http://siteB.com/index.cmrl">
<cmrlCreatedTime></cmrlCreatedTime>
<cmrlHosted>notFound</cmrlHosted>
<cmrlModifiedTime></cmrlModifiedTime>
<cmrlSize>0</cmrlSize>
<urlKey>1666d-llaf0-xb86y-zsnbc</urlKey>
</item>
</urls>
</result>
A.16. destroySubaccount
Description
Destroy an existing subaccount. Note: In order to destroy a subaccount, all services and URLs that belong to the subaccount must fist be removed first. This can be accomplished via calls to the deleteService and deleteURL methods, respectively.
Access
This method must be accessed via an HTTP POST request.
Parameters
| Name | Description |
| subaccount | Subaccount to be destroyed. |
Response
This method provides no method-specific response.
Example Invocation
URL encode the following parameters and POST to https://dotgo.com/api/1.0/:
apiKey=abcdefghijklmnopqrstuvwxy
apiPassword=asdfghjkl
method=destroySubaccount
subaccount=clientA
Example Response
Content-Type: text/xml; charset=UTF-8 <?xml version="1.0" encoding="UTF-8"?> <result success="1"></result>
A.17. launchApplication
Description
Launch application (via a single-sign-on URL) for account or subaccount.
Access
This method must be accessed via an HTTP POST request.
Parameters
| Name | Description |
| subaccount (optional) | Subaccount for which application is to be launched. If subaccount is not specified, then application is launched for account with no subaccount. |
|
application |
Application to be
launched. |
Response
A successful call to the launchApplication method returns a response element containing the following element:
| Name | Description |
|
ssoURL |
Single-sign-on URL. |
Example Invocation
URL encode the following parameters and POST to https://dotgo.com/api/1.0/:
apiKey=abcdefghijklmnopqrstuvwxy
apiPassword=asdfghjkl
method=launchApplication
application=publisher
A.18. modifyService
Description
Modify the level of an existing service. Note: A call to this method may trigger a billing event.
Access
This method must be accessed via an HTTP POST request.
Parameters
| Name | Description |
| subaccount (optional) | Subaccount containing URL for which service is to be modified. If subaccount is not specified, then service is modified for account with no subaccount. |
| url (optional) | URL for which service is to be modified. |
|
service |
Service to be
modified. |
|
serviceLevel |
Service level of
service to be modified. |
Response
This method provides no method-specific response.
Example Invocation
URL encode the following parameters and POST to https://dotgo.com/api/1.0/:
apiKey=abcdefghijklmnopqrstuvwxy
apiPassword=asdfghjkl
method=modifyService
subaccount=clientA
url=http://siteA.com/index.cmrl
service=messaging
serviceLlevel=3
Example Response
Content-Type: text/xml; charset=UTF-8 <?xml version="1.0" encoding="UTF-8"?> <result success="1"></result>
A.19. readCMRL
Description
Read DOTGO-hosted CMRL file.
Access
This method may be accessed via an HTTP GET or POST request.
Parameters
| Name | Description |
| subaccount (optional) | Subaccount containing URL for which CMRL file is to be read. If subaccount is not specified, then CMRL file is read for account with no subaccount. |
| url | URL for which CMRL file is to be read. |
Response
A successful call to the readCMRL method returns a response element containing the following element:
| Name | Description |
| cmrlContent | CMRL content. (Note that CMRL content is XML escaped.) |
Example Invocation
URL encode the following parameters and POST to https://dotgo.com/api/1.0/:
apiKey=abcdefghijklmnopqrstuvwxy
apiPassword=asdfghjkl
method=readCMRL
subaccount=clientA
url=http://siteA.com/index.cmrl
Example Response
Content-Type: text/xml; charset=UTF-8 <?xml version="1.0" encoding="UTF-8"?> <result success="1"> <cmrlContent><![CDATA[<cmrl account="wwww-xxxx-yyyy-zzzz"><match pattern=*> <content>HELLO WORLD</content></message></match></cmrl>]]></cmrlContent> </result>
A.20. reloadURL
Description
Reload URL (e.g. after writeCMRL).
Access
This method must be accessed via an HTTP POST request.
Parameters
| Name | Description |
| subaccount (optional) | Subaccount containing URL to be reloaded. If subaccount is not specified, then URL is reloaded for account with no subaccount. |
| url | URL to be reloaded. |
Response
This method provides no method-specific response.
Example Invocation
URL encode the following parameters and POST to https://dotgo.com/api/1.0/:
apiKey=abcdefghijklmnopqrstuvwxy
apiPassword=asdfghjkl
method=reloadURL
subaccount=clientA
url=http://siteA.com/index.cmrl
Example Response
Content-Type: text/xml; charset=UTF-8 <?xml version="1.0" encoding="UTF-8"?> <result success="1"></result>
A.21. sendMessage
Description
Send message (to an individual recipient) from URL of an account or subaccount.
Access
This method must be accessed via an HTTP POST request.
Parameters
| Name | Description |
| subaccount (optional) | Subaccount containing URL from which message is to be sent. If subaccount is not specified, then message is sent from account with no subaccount. |
| url | URL from which message is to be sent. |
| pathTo | Registered path to which message is to be sent. |
|
channel(optional) |
Channel through which sent message is to be sent.
(Default: 368266.) |
| node | Node to be sent. Note that node must be a valid CMRL terminating node. |
| sendTime (optional) | Time at which message is to be sent. (Default: send immediately.) |
Response
A successful call to the sendMessage method returns a response element containing the following element:
| Name | Description |
|
message |
Message that was sent.
(Note that message is a string that uniquely identifies the message that
was sent.) |
Example Invocation
URL encode the following parameters and POST to https://dotgo.com/api/1.0/:
apiKey=abcdefghijklmnopqrstuvwxy
apiPassword=asdfghjkl
method=sendMessage
url=http://site.com/index.cmrl
pathTo=janeDoe
node=<message><content>Hello Jane Doe.</content></message>
channel=368266
Example Response
Content-Type: text/xml; charset=UTF-8 <?xml version="1.0" encoding="UTF-8"?> <result success="1"> <messsage>A123-B456</messsage> </result>
A.22. unfollow
Description
Unfollow a followed path of URL of an account or subaccount.
Access
This method must be accessed via an HTTP POST request.
Parameters
| Name | Description |
| subaccount (optional) | Subaccount containing URL with followed path to be unfollowed. If subaccount is not specified, then followed path is unfollowed from account with no subaccount. |
| url | URL with followed path to be unfollowed. |
| followedPath | Followed path to be unfollowed. |
| followerPath | Follower path following followed path. |
Response
This method provides no method-specific response.
Example Invocation
URL encode the following parameters and POST to https://dotgo.com/api/1.0/:
apiKey=abcdefghijklmnopqrstuvwxy
apiPassword=asdfghjkl
method=unfollow
subaccount=clientA
url=http://siteA.com.com/index.cmrl
followerPath=jane@
followedPath=coupons
Example Response
Content-Type: text/xml; charset=UTF-8 <?xml version="1.0" encoding="UTF-8"?> <result success="1"></result>
A.23. unregister
Description
Unregister a registered path of URL of an account or subaccount. Note: Unregistering a registered path will unfollow all paths following all paths of the URL.
Access
This method must be accessed via an HTTP POST request.
Parameters
| Name | Description |
| subaccount (optional) | Subaccount containing URL to be unregistered. If subaccount is not specified, then URL is unregistered for account with no subaccount. |
| url | URL to be unregistered. |
| registeredPath | Registered path to be unregistered. |
Response
This method provides no method-specific response.
Example Invocation
URL encode the following parameters and POST to https://dotgo.com/api/1.0/:
apiKey=abcdefghijklmnopqrstuvwxy
apiPassword=asdfghjkl
method=unregister
subaccount=clientA
url=http://siteA.com.com/index.cmrl
registeredPath=jane@
Example Response
Content-Type: text/xml; charset=UTF-8 <?xml version="1.0" encoding="UTF-8"?> <result success="1"></result>
A.24. writeCMRL
Description
Write DOTGO-hosted CMRL file.
Access
This method must be accessed via an HTTP POST request.
Parameters
| Name | Description |
| subaccount (optional) | Subaccount containing URL for which CMRL file is to be written. If subaccount is not specified, then CMRL file is written for account with no subaccount. |
| url | URL for which CMRL file is to be written. |
| cmrlContent(optional) | CMRL content to be written. Note that CMRL content must be XML escaped. (Default DOTGO parked page) |
Response
This method provides no method-specific response.
Example Invocation
URL encode the following parameters and POST to https://dotgo.com/api/1.0/:
apiKey=abcdefghijklmnopqrstuvwxy
apiPassword=asdfghjkl
method=writeCMRL
subaccount=clientA
url=http://siteA.com/index.cmrl
cmrlContent=<?xml version="1.0" encoding="UTF-8"?><cmrl><match pattern="*"><message><content>Hello World!</content></message></match></cmrl>
Example Response
Content-Type: text/xml; charset=UTF-8 <?xml version="1.0" encoding="UTF-8"?> <result success="1"></result>
Appendix B. Data Type Reference
This appendix describes the various data types that can be returned as the result of a successful call to the DOTGO Reseller API, the relevant methods, the attributes, and the content.
B.1. applicationType
Description
The applicationType data type is used to describe DOTGO applications.
B.3. cmrlHostedStatusType
Description
The cmrlHostedStatusType data type is used to describe the hosted status of CMRL files.
Content
The cmrlHostedStatusType data type is a string that can take on the following values:
| Value | Description |
| notFound | URL added to account but no CMRL found for URL. |
| internal | File is hosted by DOTGO and domain ownership has been verified. |
| internalNotVerified | File is hosted by DOTGO but domain ownership has not been verified. |
| remote | File is hosted by an external server. |
| custom | File is managed by DOTGO. |
B.4. followType
Description
The followType data type is used to describe information about the relationships between followed paths and follower paths.
Attributes
The followType data type contains the following attributes:
| Attribute | Description |
| count | Count of follows. |
| displayed | Displayed number of results returned. |
| offset | Offset of results returned. |
Content
The followType data type contains one or more item elements, each of which contains the following attributes:
| Attribute | Description |
| followedPath | Followed path. |
| followerPath | Follower path. |
| subaccount | Subaccount containing URL containing followed and follower paths. |
| url | URL containing followed and follower paths. |
Each item element is empty.
B.5. followedPathsType
Description
The followedPathsType data type is used to describe information about followed paths.
Attributes
The followedPathsType data type contains the following attributes:
| Attribute | Description |
| count | Count of followed paths. |
| displayed | Displayed number of results returned. |
| offset | Offset of results returned. |
Content
The followedPathsType data type contains one or more item elements, each of which contains the following attributes:
| Attribute | Description |
| followedPath | Followed path. |
| subaccount | Subaccount containing URL containing followed path. |
| url | URL containing followed path. |
Each item element contains the following elements:
| Name | Description |
| numFollowers | Number of followers. |
B.6. messageStatusType
Description
The messageStatusType data type is used to describe information about message status.
B.7. messagesType
Description
The messagesType data type is used to describe information about messages.
Attributes
The messagesType data type contains the following attributes:
| Attribute | Description |
| count | Count of messages. |
| displayed | Displayed number of results returned. |
| offset | Offset of results returned. |
Content
The messagesType data type contains one or more item elements, each of which contains the following attributes:
| Attribute | Description |
| subaccount | Subaccount containing URL containing messages. |
| url | URL containing messages. |
Each item element contains the following elements:
| Name | Description |
| channel | Channel through which message was sent. |
| pathTo | Path to which message was sent. |
| node | Node that was sent. |
| timeCreated | Time message was created. |
| timeStart | Time message delivery was started. |
| timeStop | Time message delivery was stopped. |
|
messageStatus |
Message status.
|
B.8. registeredPathsType
Description
The registeredPathsType data type is used to describe information about registered paths.
Attributes
The registeredPathsType data type contains the following attributes:
| Attribute | Description |
| count | Count of registered paths. |
| displayed | Displayed number of results returned. |
| offset | Offset of results returned. |
Content
The registeredPathsType data type contains one or more item elements, each of which contains the following attributes:
| Attribute | Description |
| registeredPath | Registered path. |
| subaccount | Subaccount containing URL containing registered path. |
| url | URL containing registered path. |
Each item element contains the following elements:
| Name | Description |
| registrationTime | Registration time. |
B.12. serviceStatusType
Description
The serviceStatusType data type is used to describe information about a service status.
B.13. servicesType
Description
The servicesType data type is used to describe information about services.
Attributes
The servicesType data type contains the following attributes:
| Attribute | Description |
| count | Count of services. |
| displayed | Displayed number of results returned. |
| offset | Offset of results returned. |
Content
The servicesType data type contains one or more item elements, each of which contains the following attributes:
| Attribute | Description |
|
service |
Service. |
| subaccount | Subaccount containint URL containign service. |
| url | URL containing service. |
Each item element contains the following elements:
| Name | Description |
| billingPeriod | Billing period of service. |
| coupon | Coupon applied to service. |
| discount | Discount applied to service. |
| initialCost | Initial Cost (in USD) of service per billing period, before application of coupons and discounts. |
| lastBilledTime | Last billed time. |
| nextBilledTime | Next billed time. |
|
serviceDetails |
Service
details. |
|
serviceStatus |
Service status.
|
B.14. subaccountsType
Description
The subaccountsType data type is used to describe subaccounts.
Attributes
The subaccountsType data type contains the following attributes:
| Attribute | Description |
| count | Count of subaccounts. |
| displayed | Displayed number of results returned. |
| offset | Offset of results returned. |
Content
The subaccountsType data type contains one or more item elements, each of which contains the following attributes:
| Attribute | Description |
|
service |
Service described by
item. |
| subaccount | The subaccount that the service was purchased for. |
| url | The url that the service was purchased for. |
Each item element contains the following elements:
| Name | Description |
| billingPeriod | Billing period. |
| coupon | Coupon that may be applied to service. |
| discount | Discount that may be applied to service. |
| initialCost | Initial Cost (in USD) of the service per billing period before application of coupons and discounts. |
| lastBilledTime | Time of last billing event. |
| nextBilledTime | Time of next billing event. |
| serviceDetails | Details specific to the service. |
|
serviceStatus |
Service status.
|
B.15. urlsType
Description
The urlsType data type is used to describe information about URLs.
Attributes
The urlsType data type contains the following attributes:
| Attribute | Description |
| count | Count of URLs. |
| displayed | Displayed number of results returned. |
| offset | Offset of results returned. |
Content
The urlsType data type contains one or more item elements, each of which contains the following attributes:
| Attribute | Description |
| subaccount | Subaccount containing URL. |
| url | URL. |
Each item element contains the following elements:
| Name | Description |
| cmrlCreatedTime | CMRL file created time. |
| cmrlHosted | CMRL hosted status. |
| Type: cmrlHostedStatusType | |
| cmrlModifiedTime | CMRL file modified time. |
| cmrlSize | CMRL file size (in bytes). |
| urlKey | URL key. |
Appendix C. Response Error Reference
This appendix enumerates the various error codes that can be returned as the result of a call to the DOTGO Reseller API, listing for each error the error code and the error description.
-
0: Success.
-
1: Unknown error.
-
2: Permission denied.
-
3: API access disabled, please contact suppoertdotgo.com.
-
100: Unknown method.
-
101: Invalid parameters.
-
102: Unknown format.
-
103: Invalid URL format.
-
104: Invalid value for limit.
-
105: Invalid value for offset.
-
1000: Message error.
-
1001: No user registered to path.
-
1002: Couldn't send node.
-
1003: Message already sent.
-
1004: Message already cancelled.
-
1101: Invalid send node.
-
1102: Invalid time.
-
1103: Invalid designator.
-
1104: Invalid channel.
-
1105: Invalid pathTo.
-
1106: Invalid message identifier.
-
2000: Account error.
-
2100: No such subaccount.
-
2101: Subaccount identifier exists.
-
2102: Cannot create subaccount with that name.
-
2103: Cannot destroy subaccount with premium services. First call deleteService.
-
2200: No such URL.
-
2201: URL already added.
-
2202: Invalid urlKey.
-
2203: Cannot destroy url with premium services. First call deleteService.
-
3000: Service error.
-
3001: Unknown service.
-
3002: Unable to enable service, please contact support@dotgo.com.
-
3003: A service has already been added for the given URL. Use modifyService or deleteService to change the service.
-
3004: A service has not yet been added for the given URL. Use addService to add a service.
-
3005: Request to modifyService failed because the new settings match the current settings.
-
3100: Coupon unknown.
-
3101: Coupon cannot be used yet.
-
3102: Coupon expired.
-
3103: Coupon has reached use limit.
-
3104: Coupon not applicable for given service.
-
3105: Coupon may not be used for messaging plans under reseller accounts.
-
3106: Coupon minimum cost not met.
-
3200: Service update error.
-
3201: Service updates completed.
-
4000: Payment error.
-
4001: Payment database error.
-
4002: No billing information.
-
4003: Invalid billing information
-
4004: Billing information declined.
-
4005: Payment gateway error
-
4006: Billing complete.
-
5000: CMRL error.
-
5001: Unable to access CMRL file.
-
5002: Invalid CMRL format.
-
6000: Affiliate error.
-
6001: Affiliate unknown.
-
6002: Cannot replace affiliate.
-
6003: Affiliate program has not begun.
-
6004: Affiliate program has ended.