Mail Application Development Platform API Reference

This is the javascript API for building applications for Yahoo! Mail.

General Information
  • Many code samples are taken from "Kitchen Sink", "Memories", and "Saved Searches" sample applications. These applications can be found in the Application Gallery if you log in to Yahoo! Mail with an account signed up for development. Visit us on YDN to learn how to sign up and view the sample applications.
  • Very few API calls are synchronous. When data is returned, it's returned through a handler function.

Methods
  • This is the most common signature for API methods: 
    errorCode:int APICall(args:object, handler:function)

    Note: Exceptions include some calls that don't take arguments, some that don't take a handler, and some that don't take either.
    Note: A call may return undefined - this is equivalent to ERR_NONE and indicates that the call succeeded.
  • Handlers always have the following signature: 
    void handler(response:object)

Response Objects
  • Possible members for the response object are listed below. Response object, however, can only have either the error member or the warn member. If an error occurs, the response object will probably not have a data object. 
    {

    error:int,
warn:int,
errorMsg:String,
errorObj:Object,
data:Object

    
}
  • If the call succeeds, error will be absent or ERR_NONE will be returned. ERR_NONE is defined as 0, so success is indicated by !error.
  • General error codes are defined in the class openmail. Individual classes can define their own specific error codes.
  • An error code can be returned in warn if the call succeeded but had some issues. Only one of either error or warn can be present. If warn is present, errorMsg and errorObj may have values to provide additional information about the warning.
  • errorMsg is an informational message intended for debugging only.
  • errorObj may contain rich error information defined by the individual method that was called.
  • data contains the data returned by individual method that was called. If data is present, it is guaranteed to be an object. Members of the object are defined by individual method called.
  • Additional members can be defined by the method called.

General Error Information
  • The data type for all error codes is int because errors are actually enumerations and not numbers.
  • Only simple errors can be detected and returned synchronously. Expect most errors to be communicated through the handler.
  • Any error which is returned synchronously will also be passed to the handler. The handler will most likely be called before the function returns.
  • When API calls are used in sandbox, the return value is undefined instead of error code.

API Versions and Backward Compatability
  • Each update to the API undergoes a testing process to ensure all new API calls and existing API calls work as described. Once the API updates are ready for release all the sample applications available in the developers' Application gallery will be updated to use the latest API version.
  • We will strive to maintain backward compatibility. Methods may be extended (an args object may accept additional data, or response.data may return additional information), but calls made against an older version of the API will continue to work.
  • Each version of the API contains its own documentation as comments. Documentation available at official Yahoo! Developer Network will reflect the latest version of the API. If you are not using the latest version you can check the comments in the API version you are using for the correct information.
  • In the cases where we are unable to maintain backward compatibility, deprecated methods will remain in the API but will return ERR_DELETED.
  • You can figure out the API version number by the included JS URL. For example, the version number of the following URL is 0.1.2: http://redirect.corp.yahoo.com/?url=http://mail.yimg.com/a/lib/om/om_api_public/0.1.2/om_api_public.js.

Getting Started