Mail Applications Quick Start

Get the Dev Tool and Sign Up

The Yahoo! Mail Development Tool (ymdt) is a command-line utility for interacting with ou development platform. It's a php command-line script, so you need a basic php installation (no webserver required.) Many systems already have php installed. If yours doesn't, you can get it here. The only extensions needed are curl with SSL and json, which are usually installed by default. Be sure to add the php executable to your path.

Once you can type php at a command prompt and php runs, download ymdt and put it somewhere in your path.

On unixy systems, you might have to chmod u+x ymdt. On Microsoft Windows, create a ymdt.bat file in the same directory where you put ymdt and save this text in it:

@echo off
php %~sp0\ymdt %*

@echo off
php %~sp0\ymdt %*

To start development, run ymdt as shown below, and log on with the same username and password you use for Yahoo! Mail.

> ymdt signup
 
Yahoo! Mail Development Tool Version 1.07
Developer server: developer.mail.yahoo.com
signup:
Yahoo! ID: Liam
Password: ******
An authentication token has been stored in /homes/liam/.ymdtcookie
 
Until its expiration, ymdt will use it to login.
To disable this behavior, use the -d option.
 
Congratulations, you can now build apps for Yahoo! Mail.

> ymdt signup
 
Yahoo! Mail Development Tool Version 1.07
Developer server: developer.mail.yahoo.com
signup:
Yahoo! ID: Liam
Password: ******
An authentication token has been stored in /homes/liam/.ymdtcookie
 
Until its expiration, ymdt will use it to login.
To disable this behavior, use the -d option.
 
Congratulations, you can now build apps for Yahoo! Mail.

Create Your First App

Apps plug into Yahoo! Mail using a javascript API and an XML configuration file. They can manipulate or enhance how messages are rendered, display a UI within the Yahoo! Mail chrome, respond to drag-and-dropped messages, and more. A simple application is made of a config.xml and one or more view HTML files.

Make skeletal apps using the ymdt create command. You can pass the -S option to create to generate an app copied from one of our samples. Below, we create an app based on the Hello World sample.

> ymdt create hello -S "Hello World"
 
Yahoo! Mail Development Tool Version 1.07
Developer server: developer.mail.yahoo.com
create:
Getting sample 'Hello World' into hello:
    changed appid to 30eb665imad9g.
    downloading hello/config.xml. . .
    downloading hello/auth.xml. . .
    downloading hello/views/main.html. . .
Done all gets for hello.
Application '38cpm6lij2e1l' created.
    uploading hello/auth.xml. . .
    uploading hello/config.xml. . .
    uploading hello/views/main.html. . .
Done all puts for hello.

> ymdt create hello -S "Hello World"
 
Yahoo! Mail Development Tool Version 1.07
Developer server: developer.mail.yahoo.com
create:
Getting sample 'Hello World' into hello:
    changed appid to 30eb665imad9g.
    downloading hello/config.xml. . .
    downloading hello/auth.xml. . .
    downloading hello/views/main.html. . .
Done all gets for hello.
Application '38cpm6lij2e1l' created.
    uploading hello/auth.xml. . .
    uploading hello/config.xml. . .
    uploading hello/views/main.html. . .
Done all puts for hello.

Install and Run Your App in Yahoo! Mail

Login to Yahoo! Mail in your web browser and notice the Applications Pane in the lower left corner of the page. Click the '+' icon in the Applications Pane.

This launches the Yahoo! Mail Gallery. Find the app named 'Hello World Sample App (private)' with your Yahoo! ID listed as the developer. It is marked '(private)' because only you can see it while it's under development.

Click the 'Add' button, then close the Gallery. You should now see a 'Hello World (private)' app in the Applications Pane. Click its icon and the app should launch a tab. Enter some text and click the 'compose' button. Your app uses our javascript API to open the Composer tab prepopulated with the text you entered.

That's just a simple example of how an app can manipulate the Yahoo! Mail UI.

Make Changes: Edit, Upload, Refresh

The files comprising your app are located in the local 'hello' directory that was populated when you ran ymdt create. To get an idea for how apps are put together, have a look at the files in that directory.

The contents of config.xml tell Yahoo! Mail to launch the app's "main" view in a tab once the app's icon is clicked. views/main.html defines the main view HTML. It pulls in the javascript API with the script tags in the <head> and uses one API function at the end of its demoCompose function: openmail.Mail.compose.

Let's make a simple change to Hello World. Edit the file hello/views/main.html. Add a line as shown below before the openmail.Application.compose call

mailBlob.body = 'Yahoo! Mail is the center of my universe.' + mailBlob.body;
openmail.Mail.compose(mailBlob);

mailBlob.body = 'Yahoo! Mail is the center of my universe.' + mailBlob.body;
openmail.Mail.compose(mailBlob);

Upload your changed main.html to the Yahoo! Mail developer server using ymdt put.

> ymdt put hello/views/main.html
Yahoo! Mail Development Tool Version 1.07
Developer server: developer.mail.yahoo.com
put:
    uploading hello/views/main.html. . .

> ymdt put hello/views/main.html
Yahoo! Mail Development Tool Version 1.07
Developer server: developer.mail.yahoo.com
put:
    uploading hello/views/main.html. . .

You should be able to see your changes by clearing your browser's cache, reloading Yahoo! Mail, and relaunching your app from the Applications pane. An even faster way to see your changes is to click the icon next to your application in the Applications pane.

Instead of typing ymdt put every time you edit a file, try using ymdt's dev-o-matic mode: ymdt dev hello.

Learn More