SupportDocumentationView as HTML

DOTGO Reseller API Reference Guide

CMRL Version 1.0

Download PDF

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.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.
Type: serviceType

serviceLevel

Service level of service to be added.
Type: serviceLevelType

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.)
Type: channelType

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.)
Type: string

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.
Type: serviceType

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.
Type: followedPathsType

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.
Type: followType

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.
Type: messagesType

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.
Type: registeredPathsType

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.
Type: servicesType

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.
Type: subaccountsType

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.
Type: urlsType

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>
Related Methods
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.
Type: applicationType

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
Example Response
Content-Type: text/xml; charset=UTF-8
<?xml version="1.0" encoding="UTF-8"?>
<result success="1">
  <ssoURL>http://dotgo.com/services/?a=s&amp;t=abCdeFg12345678aBcDEfghiJklmNOp</ssoURL>
</result>
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.
Type: serviceType

serviceLevel

Service level of service to be modified.
Type: serviceLevelType

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>
Related Methods
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.)
Type: channelType

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.)
Type: string

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>
Related Methods
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.

Content

The applicationType data type is a string that can take on the following value:

Value Description
publisher DOTGO Publisher application.
B.2. channelType
Description

The channelType data type is used to describe DOTGO channels.

Content

The channelType data type is a string that can take on the following values:

Value Description
368266 The DOTCOM (368266) channel.
368338 The DOTEDU (368338) channel.
368468 The DOTGOV (368468) channel.
368638 The DOTNET (368638) channel.
368674 The DOTORG (368674) channel.
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.

Content

The messageStatusType data type is a string that can take on the following values:

Value Description
pending Message is pending.
delivered Message is delivered.
cancelled Message is cancelled.
sending Message is being sent.
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.
Type: messageStatusType

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.9. serviceType
Description

The serviceType data type is used to describe information about a service. Currently, the only valid service is the messaging service, which enables DOTGO messaging plans.

B.10. serviceDetailsType
Description

The serviceDetailsType data type is used to describe information about details of a service (i.e. attributes that vary on a service-by-service basis).

B.11. serviceLevelType
Description

The serviceLevelType data type is used to described information about a service level. Currently, the only valid service levels (of the only valid service, the messaging service) are 1, 2, and 3, which enable the DOTGO “basic,” “standard,” and “pro” messaging plans, respectively.

B.12. serviceStatusType
Description

The serviceStatusType data type is used to describe information about a service status.

Content

The serviceStatusType data type is a string that can take on the following values:

Value Description
active Service is active.
pending Service is pending.
disabled Service is disabled.
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.
Type: serviceType

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.
Type: serviceDetailsType

serviceStatus

Service status.
Type: serviceStatusType

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.
Type: serviceType

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.
Type: serviceStatusType

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.