StesCodes

Documentation of AddressBook Importer - API(.net) version 4.0

The StesCodes AddressBook Importer provides the ability to import contacts from various mail servers and social networks in minutes. The below is the technical document to configure the grabber.
 

Getting Signature Key
The first step in using our AddressBook Importer API is getting the signature key, signature key(transaction id) is found once you make purchase and redirected to our website and also found on the email which you receive from StesCodes after you make purchase. The transaction id of StesCodes is refered to as signature key.

Inorder to use the trial, you need to generate the key here http://stescodes.com/trial.aspx. You shall get the key based on the selection of plan.
back to top

AddressBook Importer
The next step after getting the signature key is to creating reference.

Reference
  • Add reference to stescodes_eval.dll on your project bin folder
  • Import the namespace "stescodes_eval"
Note: You shall download the stescodes_eval.dll for .net 2008 here Download
You shall download the stescodes_eval.dll for .net 2010 here Download

Direct Method

Request
Make a request to https://stescodes.com/addressbookapi.aspx using "POST" method, to grab contacts from various mail servers.

Parameters
Parameters Description Required?
1. ServiceName Service Name refers to the mail servers. Inorder to access a service use the below reference keywords
aol, outlook, icq, pingg, mail.com, aim, plaxo, bigstring, mail2world, in.com, rediff, freenet, gmx

Note: For gmail, yahoo, msn, hotmail and msnmessenger, we recommend to use the OAuth Method

 Yes
2. Signature Formated Signature:
In order to format the signature key, make reference of "processor" class and then pass your signature key along with the HttpContext object associated with the page as input parameter to "getSecretKey", which is a function of "processor" class. The signature must be formatted before making a request. 		Yes
3. username Login email of the particular email server. This field is required for all services except outlook or csv grabbing requests. Yes/No
4. filename The http url of the csv file, The request url should be a online csv file url (eg:"http://stescodes.com/text.csv") and localhost url won't work. This field is required only for outlook or csv grabbing requests. Yes/No
5. Password Login password of the particular email server. Yes
6. Format
  • JSON - (by default)
  • XML
 Yes

Response
The return type is a of format JSON and XML, below are the example response of JSON and XML formats.

JSON response:

                    
          [ { "name": "stescodes", "email" : "support@stescodes.com",
              "address" : "xxx montecito ave, Mountain View CA 94043", "phone" : "xxx-xxx-xxxx"} ]

XML response:

                    
                    <?xml version="1.0" encoding="utf-8"?>
                    <servicename> 
                        <contacts> 
                            <name>stescodes</name> 
                            <email>support@stescodes.com</email> 
                            <address>xxx montecito ave, Mountain View CA 94043</address> 
                            <phone>xxx-xxx-xxxx</phone> 
                        </contacts> 
                    </servicename>
back to top

OAuth Method

To start grabbing contacts using OAuth Method, you have to make request to three functions

  1. GetAuthenticationUrl
  2. GetAccessToken
  3. GrabContacts_OAuth

To configure API keys in Gmail, Yahoo and Windows Live, click here How to configure API keys.

Request for GetAuthenticationUrl

Make a request to https://stescodes.com/addressbookapi.aspx using "GET" method (Please url encode the parameter values).


            https://stescodes.com/addressbookapi.aspx?
                                 ServiceName=<servicename>&
                                 ConsumerKey=<your consumer key>&
                                 ConsumerSecret=<your consumer secret key>&
                                 CallbackUrl=<return url>&
                                 PolicyUrl=<policy page url>&
                                 format=<return format>

Parameters
Parameters Description Required?
1. ServiceName Service Name refers to the mail servers. Inorder to access a service use the below reference keywords
gmail, yahoo, msn, hotmail and msnmessenger 		Yes
2. ConsumerKey Consumer key(API Key) which you received after registering you application on gmail, yahoo, msn, hotmail and msnmessenger Yes
3.ConsumerSecret Consumer Secret(APi Secret) which you received after registering you application on gmail, yahoo, msn, hotmail and msnmessenger Yes
4. CallbackUrl CallbackURL is the return url which is used, once the user is redirected to authorize, he/she will be redirected to the callbackurl (note: sometimes you might get error with callbackurl between www.xx.com and xx.com, so carefull with www) Yes
5. PolicyUrl URL of your policy page. Yes
6. Format
  • JSON - (by default)
  • XML
 Yes

Response
The return type is a of format JSON and XML, below are the example response of JSON and XML formats.

JSON response:

                    
            { "token": "your token", "tokensecret" : "your token secret",
                            "authurl" : "your authentication url", "uid" : "User id" }

XML response:

                    
            <?xml version="1.0"?>
            <ArrayOfAuthdetails xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
                                                        xmlns:xsd="http://www.w3.org/2001/XMLSchema">
                <authdetails>
                    <token>your token</token>
                    <tokensecret>your token secret</tokensecret>
                    <authurl>your authentication url</authurl>
                    <uid>user id</uid>
                </authdetails>
            </ArrayOfAuthdetails>
back to top

Request for GetAccessToken

Make a request to https://stescodes.com/addressbookapi.aspx using "GET" method (Please url encode the parameter values).


            https://stescodes.com/addressbookapi.aspx?
                                 ServiceName=<servicename>&
                                 ConsumerKey=<your consumer key>&
                                 ConsumerSecret=<your consumer secret key>&
                                 CallbackUrl=<return url>&
                                 Token=<your token>&
                                 TokenSecret=<your token secret>&
                                 TokenVerifier=<your token verifier>&
                                 format=<return format>

Parameters
Parameters Description Required?
1. ServiceName Service Name refers to the mail servers. Inorder to access a service use the below reference keywords
gmail, yahoo, msn, hotmail and msnmessenger 		Yes
2. ConsumerKey Consumer key(API Key) which you received after registering you application on gmail, yahoo, msn, hotmail and msnmessenger Yes
3.ConsumerSecret Consumer Secret(APi Secret) which you received after registering you application on gmail, yahoo, msn, hotmail and msnmessenger Yes
4. CallbackUrl CallbackURL is the return url which is used, once the user is redirected to authorize, he/she will be redirected to the callbackurl (note: sometimes you might get error with callbackurl between www.xx.com and xx.com, so carefull with www) Yes
5. Token Token received after authentication. Yes
6. TokenSecret Your token secret Yes
7. TokenVerifier Token verifier received after authentication. Yes
8. Format
  • JSON - (by default)
  • XML
 Yes

Response
The return type is a of format JSON and XML, below are the example response of JSON and XML formats.

JSON response:

                    
            { "token": "your token", "tokensecret" : "your token secret",
                            "authurl" : "your authentication url", "uid" : "User id" }

XML response:

                    
            <?xml version="1.0"?>
            <ArrayOfAuthdetails xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
                                                        xmlns:xsd="http://www.w3.org/2001/XMLSchema">
                <authdetails>
                    <token>your token</token>
                    <tokensecret>your token secret</tokensecret>
                    <authurl>your authentication url</authurl>
                    <uid>user id</uid>
                </authdetails>
            </ArrayOfAuthdetails>
back to top

Request for GrabContacts_OAuth
Make a request to https://stescodes.com/addressbookapi.aspx using "POST" method, to grab contacts from various mail servers(Please url encode the parameter values).

Parameters
Parameters Description Required?
1. ServiceName Service Name refers to the mail servers. Inorder to access a service use the below reference keywords
gmail, yahoo, msn, hotmail and msnmessenger 		Yes
2. Token Your access token. Yes
3. TokenSecret Your token secret Yes
4. TokenVerifier Your Token verifier. Yes
5. Uid Your user id Yes
6. Signature Formated Signature:
In order to format the signature key, make reference of "processor" class and then pass your signature key along with the HttpContext object associated with the page as input parameter to "getSecretKey", which is a function of "processor" class. The signature must be formatted before making a request. 		Yes
7. ConsumerKey Consumer key(API Key) which you received after registering you application on gmail, yahoo, msn, hotmail and msnmessenger Yes
8.ConsumerSecret Consumer Secret(APi Secret) which you received after registering you application on gmail, yahoo, msn, hotmail and msnmessenger Yes
9. Format
  • JSON - (by default)
  • XML
 Yes

Response
The return type is a of format JSON and XML, below are the example response of JSON and XML formats.

JSON response:

                    
          [ { "name": "stescodes", "email" : "support@stescodes.com",
              "address" : "xxx montecito ave, Mountain View CA 94043", "phone" : "xxx-xxx-xxxx"} ]

XML response:

                    
                    <?xml version="1.0" encoding="utf-8"?>
                    <servicename> 
                        <contacts> 
                            <name>stescodes</name> 
                            <email>support@stescodes.com</email> 
                            <address>xxx montecito ave, Mountain View CA 94043</address> 
                            <phone>xxx-xxx-xxxx</phone> 
                        </contacts> 
                    </servicename>
back to top

Debugging

Debugging Gmail:

  1. Create API key with the localhost url as return url(when going live, change the return url to live url)
  2. Replace the api key and secret key in web.config file
  3. Replace the already provided localhost url in oauth.aspx.cs file
  4. Then try with breakpoints to debug

Debugging Yahoo:

  1. Create API key with the localhost url as return url(when going live, change the return url to live url)
  2. Replace the api key and secret key in web.config file
  3. Then try with breakpoints to debug

Debugging Windows Live:

Debugging for Hotmail, MSN and msnmessenger is hard when compared to other services because in OAuth method, for the three services, you receive the token in post data other than in querystring. So follow the below steps to debug in local
  1. Upload the auth.aspx page to your server.
  2. Do the below five steps when the user is redirected after authentication.
  3. Get the post data and construct as a url with querystring parameter(for ex: token=xxx&tokensecret=yyyy as http://youdomain.com/auth.aspx?token=xxx&tokensecret=yyyy)
  4. After constructing the parameter change the constructed url to localhost url(for ex: http://youdomain.com/auth.aspx?token=xxx&tokensecret=yyyy to http://localhost:2345/yourproject/auth.aspx?token=xxx&tokensecret=yyyy
  5. Redirect to the localhost url(for ex: Response.Redirect(http://localhost:2345/yourproject/auth.aspx?token=xxx&tokensecret=yyyy);)
  6. Now you will get the token in localhost for debugging.
  7. Remove the redirection part after you done with your debugging.
back to top

Binding
Once the contacts are grabbed and received in requested formats, it should be deserialized and you shall loop through to access the contacts. Binding the data to front end is all customizable.
back to top

Error Handling
There are few error messages you need to taken care on your end

Error Message
Error Description
1. Invalid domain The license(Signature Key) is not registered for this domain. You shall change/edit your domain here http://stescodes.com/sourceupdate.aspx
2. Invalid key The Signature Key is invalid.
3. Invalid username & password The username or password is invalid.
4. Please try again Please try again one more time.
5. Please login to http://www.gmail.com and then try again If the user account is not used for long time Gmail will ask for CAPTCHA authentication, so user have to login to his account and then try importing.
6. Missing input Missing the input parameter
7. This service not available on your plan The service you are requesting to grab contacts are not available on your purchased plan.
back to top

Change Domain
If you get the domain is invalid and you purchased license for that domain, then you shall follow the below steps to update your domain.

Edit/Change Domain
To edit or change your domain
  • Login to http://stescodes.com/sourceupdate.aspx
  • You shall login using email and password which you received in email during purchase or you shall use the StesCodes transaction id
  • Once you login, click the edit link near website
  • Enter the domain details
  • Click "proceed" to save.
back to top
HOME | TERMS OF SERVICE | PRODUCT | CONTACT US | PRIVACY POLICY | FAQ | SITE MAP
Copyright 2011 stescodes.com