Calling the Yahoo! Mail Web Service

OAuth Scopes and AuthService Setup

Yahoo! Mail Web Service (YMWS) calls are protected using OAuth. Your app can only access YMWS methods allowed by the scopes associated with its OAuth Consumer key. Configuring your app for accessing an endpoint that supports OAuth is explained in detail here.

There are two different ways to configure your scopes and get an AuthService object prepared to call web services:

Self Service

Obtain a key and secret from developer.yahoo.com. This is completely self-service, which is nice, but you have to do some work to orchestrate user authorization before you have an AuthService instance prepared to do web service calls.

Refined for Yahoo! Endpoints

Have a Yahoo! Mail Development Platform administrator configure your app to use OAuth refinements for Yahoo! endpoints. In this case, the keys and secrets (and scopes) are all managed by our server -- you don't need anything in your auth.xml. The user experience is stream-lined as well. It is easy to upgrade from the self-service approach to this one, so we don't normally enable Yahoo! endpoint refinements until your app is nearly ready for production.

If we do enable this support for your app, all you have to do to have an AuthService instance ready to call your webservice is this:

 
   var auth = openmail.Application.getAuthService({});

 
   var auth = openmail.Application.getAuthService({});

YQL Examples

Assuming you've got an AuthService instance auth with the mail read-summary scope and that you've prepared it to make webservice calls in one of these ways, you're ready to talk to YQL. You could query YQL for the logged-on user's folder names using this code:

auth.callWebService({
    url: 'http://query.yahooapis.com/v1/yql',
    method: 'GET',
    parameters: {
        format: "json",
        q: 'select * from ymail.folders'
    },
    function(args) {
        console.log("got data: ", args.data);
    }
}); 

auth.callWebService({
    url: 'http://query.yahooapis.com/v1/yql',
    method: 'GET',
    parameters: {
        format: "json",
        q: 'select * from ymail.folders'
    },
    function(args) {
        console.log("got data: ", args.data);
    }
}); 

GetUserData Example

This code uses AuthService.callWebService to call the Yahoo! Mail Webservice GetUserData method.

 
//Invoked when the webservice responds
function onResults(args){
    console.log('got ws result', args);
}
 
var auth = openmail.Application.getAuthService({}),
    url = 'http://mail.yahooapis.com/ws/mail/v1.1/jsonrpc',
    params = [{}],
    method = 'GetUserData';
 
auth.callWebService({
        url: url,
        method:"POST",
        headers: [ 'content-type:application/json' ],
        parameters: {},
        body: YAHOO.lang.JSON.stringify({
               method: method,
               params: params,
               id: "123456789"
        })
    },
    onResults);
 

 
//Invoked when the webservice responds
function onResults(args){
    console.log('got ws result', args);
}
 
var auth = openmail.Application.getAuthService({}),
    url = 'http://mail.yahooapis.com/ws/mail/v1.1/jsonrpc',
    params = [{}],
    method = 'GetUserData';
 
auth.callWebService({
        url: url,
        method:"POST",
        headers: [ 'content-type:application/json' ],
        parameters: {},
        body: YAHOO.lang.JSON.stringify({
               method: method,
               params: params,
               id: "123456789"
        })
    },
    onResults);
 

ListMessages Example

This code uses the YMWS ListMessages method to list the first ten messages in the user's "Draft" folder:

 
//Invoked when the webservice responds
function onResults(args){
    console.log('got ws result', args);
}
 
var auth = openmail.Application.getAuthService({}),
    url = 'http://mail.yahooapis.com/ws/mail/v1.1/jsonrpc',
    params = [{fid:'Draft', numMid:10}],
    method = 'ListMessages';
 
        auth.callWebService(
          {
            url: url,
            method:"POST",
            headers: [ 'content-type:application/json' ],
            parameters: {},
            body: YAHOO.lang.JSON.stringify({
                    method: method,
                    params: params,
                    id: "123456789"
                })
          },
          onResults);
}
 

 
//Invoked when the webservice responds
function onResults(args){
    console.log('got ws result', args);
}
 
var auth = openmail.Application.getAuthService({}),
    url = 'http://mail.yahooapis.com/ws/mail/v1.1/jsonrpc',
    params = [{fid:'Draft', numMid:10}],
    method = 'ListMessages';
 
        auth.callWebService(
          {
            url: url,
            method:"POST",
            headers: [ 'content-type:application/json' ],
            parameters: {},
            body: YAHOO.lang.JSON.stringify({
                    method: method,
                    params: params,
                    id: "123456789"
                })
          },
          onResults);
}
 

Calling from Your Server

If your application includes a server-side component that you host, you have the option of making YMWS calls directly from your server instead of from the javascript running in the browser. In this case, you sign up on YDN for an "app key" (unrelated to your Yahoo! Mail app) for your server and access YMWS as documented here.

Be sure to use the JSON client and not the SOAP client. The SOAP client is getting deprecated.

Support & Community