Quick Start

This section will help you to get quickly up and running using the Yahoo! Mail APIs.

In order to use the Yahoo! Mail APIs, you first need to access your user’s data, with their permission, using Brower-Based Authentication (BBA). This guide assumes you already know how to get started with BBA. See the BBAuth section on Yahoo! Developer Network for more information.

The following steps will take you through the proccess.

●	Credential the User

●	Construct the SOAP Client

●	Determine the User’s Account Capabilities

●	Make Subsequent Calls

●	Batch Calls

Code samples in this guide are written in PHP; however, other languages will have similar mappings.

Limitations

Currently, the Yahoo! Mail Web Service APIs cannot access Yahoo! Business Mail or Yahoo! Japan Mail accounts.

Credential the User

Before you begin, you must follow the steps on the BBAuth quick start, and load the web service session ID (WSSID) and the credentials for the current user.

In addition, you will need the application ID issued to you when you signed up for access to the Yahoo! Mail Web Service.

Construct the SOAP Client

Use WSDL to construct your SOAP client. Even though a service endpoint URL is indicated in the WSDL, you must provide a location URL to your SOAP toolkit. This is necessary to transmit the application ID and the WSSID. In addition, you must set the cookie header containing the cookie that was returned with the WSSID when you credentialed the user in the previous step.

// Construct the URL encoded URL to send requests to

$location = "http://mail.yahooapis.com/ws/mail/v1.1/soap?appid=" .              urlencode($appid) . "&WSSID=" . urlencode($wssid);

// Construct the SOAP client

$client = new SoapClient("http://mail.yahooapis.com/ws/mail/v1.1/wsdl",

array("location" => $location));

// Remove the leading "Y=" from the cookie string

$credential = split("=", $cookie);

// Set the "Y" cookie in the SOAP client

$client->__setCookie("Y", $credential[1]);

Determine the User’s Account Capabilities

The Yahoo! Mail Web Service limits the functionality available to free accounts. Premium accounts have no such limits. First call the GetUserData method to get the user’s account type from the web service.

Account Types

●	Premium Users

Premium users may access any part of the web service. There are no restrictions.

●	Non-Premium Users

Non-Premium users are restricted to the following APIs:

ListFolders	ListMessages	DeleteMessages
GetUserData	BatchExecute	CreateFolder
FetchExternalMail	RemoveFolder	RenameFolder
MoveMessages	EmptyFolder

Calls to other APIs will return an error. To upgrade to premium, go to mailplus.mail.yahoo.com. For information on how to receive a commission for upgrading users to a premium Yahoo! Mail Plus account see the Yahoo! Mail Web Service page on the Yahoo! Developer Network.

Calling GetUserData

Call GetUserData to find out the user’s level of service, as in the following example.

// Load the user data

$userData = $client->GetUserData();

// Check whether the user has a premium account

$isPremium = $userData->data->userFeaturePref->isPremium;

Make Subsequent Calls

Once you have determined the user’s level of service, you can make additional calls to Yahoo! Mail. For example, call the ListFolders method to get a list of folders that the user has in their mail account.

$folderList = $client->ListFolders();

Some methods require parameters passed as a single object parameter. For example, the following code creates and passes to the ListMessages method a request object containing which folder to fetch messages from, where to start, and the number of messages to fetch.

// Build the request parameters

$request = new stdclass();

$request->fid = "Inbox"; // List the Inbox folder

// Starting at the first position using the default sort order

$request->startInfo = 0;

// Fetch 20 message info objects

$request->numInfo = 20;

// Execute the list messages request

$messageList = $client->ListMessages($request);

Linking Directly To a Message

The following links will allow you to link into a user’s mailbox from another application. They will recognize whether the user is using beta mail or classic mail.

If you are not logged in already, it will force a login.

Composing a New Message

http://mrd.mail.yahoo.com/compose

Going Directly to a Message

http://mrd.mail.yahoo.com/msg?mid=[Yahoo! Mail message id]&fid=[Yahoo! Mail folder ID]

Batch Calls

The Yahoo! Mail Web Service has a call batching mechanism. Use the BatchExcecute method to excecute up to five methods in a single call. Batch calls can be chained, so that each call is dependent on the previous call’s successful execution. In addition, with the parameter field, each call can reference data specified by the source and destination paths.

Batch Call Chaining

Each batch call can have a dependency on the successful execution of other batch calls. To do this, add an id attribute to each batch call that must execute before any following calls. To subsequent batch calls, add a dependency tag that specifies the id of any calls that must successfully execute before this one. Calls with one or more dependencies will not execute unless all call(s) listed in its dependency tag have excuted.

For example, the following SOAP request calls ListMessages and GetMessages. GetMessages is dependent on ListMessages and will not execute until it successfully executes.

<SOAP-ENV:Envelope>

<SOAP-ENV:Body>

<BatchExecute>

  <call id="listMessages">

    <ListMessages startMid="0" numMid="5">

      <fid>Inbox</fid>

    </ListMessages>

  </call>

  <call id="getMessages">

    <parameter>

      <source>listMessages.mid</source>

      <destination>getMessages.mid</destination>

    </parameter>

     <dependency>listMessages</dependency>

    <GetMessage>

      <fid>Inbox</fid>

    </GetMessage>

  </call>

</BatchExecute>

</SOAP-ENV:Body>

</SOAP-ENV:Envelope>

Passing Data

You can associate data with a batch call using the parameter tag which can contain a "source" and a "destination" path. The source path specifies the location, starting with a call ID, of a piece of data. The destination path specifies the location, starting with the call ID of the current call, of a placeholder. Yahoo! Mail will look up the source path and place that piece of data into the current call request at the location given by the destination path.

The following example calls BatchExecute to create and rename a folder in one call.

// Construct the batch execute request

$batchExecuteRequest = new stdclass();

// Hold all of the calls being batched

$batchExecuteRequest->call = array();

// Construct a request to construct a new folder named "Foo"

$createRequest = new stdclass();

$createRequest->CreateFolder = new stdclass();

$createRequest->CreateFolder->name = "Foo";

// Add the request to the batch

array_push($batchExecuteRequest->call, $createRequest);

// Construct a request to rename the folder named "Foo" to "Bar"

$renameRequest = new stdclass();

$renameRequest->RenameFolder = new stdclass();

$renameRequest->RenameFolder->fid = "Foo";

$renameRequest->RenameFolder->name = "Bar";

// Add the request to the batch

array_push($batchExecuteRequest->call, $renameRequest);

// Execute the batch

$response = $client->BatchExecute($batchExecuteRequest);

Endpoints

All endpoints accept only POST requests. The requests themselves are serialized as XML, JSON or PHP and comprise the entire POST body. The request headers should indicate what content type the request is in. All endpoints accept and return UTF-8 data only.

SOAP Endpoint

SOAP can be reached by sending all calls to http://mail.yahooapis.com/ws/mail/v1.1/soap. Additionally, the WSDL for the service is available at http://mail.yahooapis.com/ws/mail/v1.1/wsdl.

SOAP Sample Request

<?xml version="1.0" encoding="UTF-8"?>

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">

  <SOAP-ENV:Body>

    <ListMessages startMid="0" startInfo="0" numMid="10" numInfo="1">

      <fid>Inbox</fid>

    </ListMessages>

  </SOAP-ENV:Body>

</SOAP-ENV:Envelope>

SOAP Sample Response

<?xml version="1.0" encoding="UTF-8"?>

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">

  <SOAP-ENV:Body>

    <ListMessagesResponse startMid="0" startInfo="0" numMid="10" numInfo="1">

      <folder unread="5" total="19" size="10358178">

        <folderInfo fid="Inbox" name="Inbox"/>

      </folder>

      <mid>1_10690_AKPPjkQAAHsRQzU1aAAnSyXpatM</mid>

      <mid>1_159_AKHPjkQAAGHKQyccZgnrGirdfks</mid>

      <mid>1_697_AKDPjkQAATdTQx+GBgWKY2C+E4I</mid>

      <mid>1_1269_AJrPjkQAAGACQx3P4gAgGnCwgUA</mid>

      <mid>1_1674_AKPPjkQAAD9pQxNdsQXkam+Ac+Q</mid>

      <mid>1_2319_AJrPjkQAARyyQwIc3gHTmApssKQ</mid>

      <mid>1_2888_AJ/PjkQAAJfZQv0SegHi008K510</mid>

      <mid>1_3504_AJvPjkQAANBLQv0NcwovmS4QtQg</mid>

      <mid>1_4112_AKHPjkQAAVulQswRLgjQF3B4YGw</mid>

      <mid>1_4676_AJrPjkQAAJjCQsXiUQ2lcSYHdMg</mid>

      <messageInfo mid="1_10690_AKPPjkQAAHsRQzU1aAAnSyXpatM" toEmail="mc_ymailsearch_test@yahoo.com"

        subject="Vote for your favorite spots in San Francisco, you could win a 2006 Mazda!"

        mimeType="multipart/alternative" externalPopServer="" receivedDate="1127551268" size="18714">

        <flags isReplied="0" isFlagged="0" isRead="0" isDraft="0" isForwarded="0" isHam="0" isSpam="0"

          hasAttachment="0" inAddressBook="0"/>

          <from>

            <name>Yahoo! Local</name>

             <email>directmail@yahoo-inc.com</email>

          </from>

      </messageInfo>

    </ListMessagesResponse>

  </SOAP-ENV:Body>

</SOAP-ENV:Envelope>

JSON-RPC Endpoint

The JSON-RPC endpoint implements the JSON-RPC spec on top of the web service. Requests are serialized JavaScript following a specific data format. Each serialized JavaScript object contains the following properties:

●	method: name of the API method being called.

●	params: an array containing the method parameters.

●	id (optional): the ID of the request, allows asynchronous clients to match a response back up with the original request.

The service responds with serialized JavaScript as well. Once again, the JavaScript object follows a specific data format:

●	result: the return from the API method, must be null if there was an error.

●	error: an error object resulting from the call being made (like an exception), must be null if there was no error.

●	id (optional): the ID specified in the request, if specified.

JSON-RPC Sample Request

{

"method":"ListMessages",

"params":

[

{

"fid":"Inbox",

"startMid":0,

"numMid":10,

"startInfo":0,

"numInfo":1

}

],

"id":1234567890

}

JSON-RPC Sample Response

{

"result":

{

"folder":

{

"folderInfo":

{

"fid":"Inbox",

"name":"Inbox"

},

"total":19,

"unread":5,

"size":10358178

},

"mid":

[

"1_10690_AKPPjkQAAHsRQzU1aAAnSyXpatM",

"1_159_AKHPjkQAAGHKQyccZgnrGirdfks",

"1_697_AKDPjkQAATdTQx+GBgWKY2C+E4I",

"1_1269_AJrPjkQAAGACQx3P4gAgGnCwgUA",

"1_1674_AKPPjkQAAD9pQxNdsQXkam+Ac+Q",

"1_2319_AJrPjkQAARyyQwIc3gHTmApssKQ",

"1_2888_AJ\/PjkQAAJfZQv0SegHi008K510",

"1_3504_AJvPjkQAANBLQv0NcwovmS4QtQg",

"1_4112_AKHPjkQAAVulQswRLgjQF3B4YGw",

"1_4676_AJrPjkQAAJjCQsXiUQ2lcSYHdMg"

],

"messageInfo":

[

{

"flags":

{

"isReplied":0,

"isFlagged":0,

"isRead":0,

"isDraft":0,

"isForwarded":0,

"isHam":0,

"isSpam":0,

"inAddressBook":0,

"hasAttachment":0

},

"from":

{

"name":"Yahoo! Local",

"email":"directmail@yahoo-inc.com"

},

"inboxservices":

[

{

"name":"allow",

"value":"all"

},

{

"name":"sbc",

"value":"9ccfff"

},

{

"name":"sih",

"value":"16"

},

{

"name":"siu",

"value":"http:\/\/us.i1.yimg.com\/us.yimg.com\/a\/di\/direct\/y_16.gif"

},

{

"name":"siw",

"value":"16"

}

],

"mid":"1_10690_AKPPjkQAAHsRQzU1aAAnSyXpatM",

"toEmail":"mc_ymailsearch_test@yahoo.com",

"subject":"Vote for your favorite spots in San Francisco, you could win a 2006 Mazda!",

"mimeType":"multipart\/alternative",

"externalPopServer":"",

"receivedDate":1127551268,

"size":18714

}

],

"numMid":10,

"startMid":0,

"numInfo":1,

"startInfo":0

},

"error":null,

"id":1234567890

}