NAME

Mail::Webmail::Yahoo - Enables bulk download of yahoo.com -based webmail.

SYNOPSIS

use Mail::Webmail::Yahoo;
$yahoo = Mail::Webmail::Yahoo->new(%options);
@folders = $yahoo->get_folder_list();
@messages = $yahoo->get_mail_messages('Inbox', 'all');
# Write messages to disk here, or do something else.

DESCRIPTION

This module grew out of the need to download a large archive of web mail in bulk. As of the module's creation Yahoo did not provide a simple method of performing bulk operations.

This module is intended to make up for that shortcoming.

METHODS

$yahoo = new Mail::Webmail::Yahoo(...)

Creates a new Mail::Webmail::Yahoo object. Pass parameters in key => value form, and these must include, at a minimum:

username
password

You may also pass an optional cookie file as cookie_file => '/path/to/file'.

$yahoo->connect();

Connects the application with the site. Really this is not necessary, but it's in here for hysterical raisins.

$yahoo->login();

Method which performs the 'login' stage of connecting to the site. This method can take a while to complete since there are at least several re-directs when logging in to Yahoo.

Returns 0 if already logged in, 1 if successful, otherwise sets $@ and returns undef.

@headers = $yahoo->get_mail_headers($folder);

***DEPRECATED***

Since this method does exactly what get_mail_messages does, it has been deprecated and will disappear at some future time.

Returns an array of message headers for the $folder folder. These are mostly in Mail::Internet format, which is nice but involves constructing them from what Yahoo provides -- which ain't much. When an individual message is requested, we can get more info via turning on the headers, so this method requests each method in turn (caching for future use, unless cache_messages is turned off) and builds a Mail::Internet object from each message.

You can get the 'raw' headers from get_folder_index().

Note that for reasons of efficiency both this method and get_mail_messages() both collect headers and the full text of the message, and this is cached to avoid having to go back to the network each time. To force a refresh, set the Snagmail object's cache to 0 with

$yahoo->cache_messages(0);
$yahoo->cache_headers(0);

Note: There used to be a $callback parameter to this method, but since it was never used it has been removed.

$page = $yahoo->download_attachment($download_uri, $mailmsg);

Downloads an attachment from the specified uri. $mailmsg is a reference to a Mail::Internet object.

@message_headers = $yahoo->get_folder_index($folder);

Returns a list of all the messages in the specified folder.

@messages = $yahoo->_get_message_links($page)

(Private instance method)

Returns the actual links (as an array) needed to pull down the messages. This method is used internally and is not intended to be used from applications, since the messages returned are not in a very friendly form.

@folders = $yahoo->get_folder_list();

Returns a list of folders in the account. Logs the user in if necessary.

$ok = $yahoo->send($to, $subject, $body, $cc, $bcc, $flags);

Attempts to send a message to the recipients listed in $to, $cc, and $bcc, with the specified subject and body text. Logs the user in if necessary.

$flags may contain any combination of the constants exported by this package. Currently, these constants are:

SAVE_COPY_TO_SENT_FOLDER  :    saves a copy of a sent message

cc and bcc come after subject and body in the parameter list (instead of with 'to') since it is expected that

send(to, subject, body)

will be more common than sending to cc or bcc recipients - at least, this is how it is in my experience.

$to, $cc and $bcc should contain comma-separated lists of email addresses, since this is what Yahoo prefers; as of this version, address-book lookups are not supported.

As of this version, mail attachments are not supported.

$resp = $yahoo->_get_a_page($uri, $method, $params);

(Private instance method)

Requests and returns a page found at the specified $uri via the specified $method. If $params (an arrayref) is present it will be formatted according to the method.

If method is empty or undefined, it defaults to GET. The ordering of the parameters, while seemingly counter-intuitive, allows one of the great virtues of programming (laziness) by not requiring that the method be passed for every call.

Returns the response object if no error occurs, otherwise undef.

$current_trace_level = $yahoo->trace($new_trace_level);

if $new_trace_level exists, sets the new level for tracing the operation of the object. Returns the current trace level (i.e. before setting a new one).

Trace levels are:

  0   no tracing output; warning messages only.
> 0   informative messages only ("what I am doing")
> 1   URIs being fetched
> 2   request response codes
> 3   request parameters
> 4   any other 'extra' debugging info.
> 9   request response content

$yahoo->debug(...);

Sends debugging messages to STDERR, appended with a newline.

EXPORTS

Nothing. The module is intended to be object-based, and functions should therefore be called using the -> operator.

CAVEATS

There is an issue somewhere that prevents https redirects from succeeding. Until this is fixed, the login procedure WILL expose the username and password in plain text over the network.

The user interface of Yahoo webmail is fairly configurable. It is possible the module may not work out-of-the-box with some configurations. It should, however, be possible to tweak the settings at the top of the file to allow conformance to any configuration.

AUTHOR

Simon Drabble  E<lt>sdrabble@cpan.orgE<gt>

SEE ALSO