NAME
WWW::Myspace::Message - Auto-message your MySpace friends from Perl scripts
VERSION
Version 0.13
WARNING
If you created your myspace account in or after June 2006 (approximately), and you use a "bot" (including this module) to send messages, your message sending ability will be disabled and your account may be deleted. This is due to security features myspace has implemented to prevent spam abuse by people using multiple accounts. This does not seem to affect older accounts, so if you've had your account since at least early 2006 you should be fine.
We don't know yet if this affects commenting or friend adding.
SYNOPSIS
use WWW::Myspace;
use WWW::Myspace::Message;
my $myspace = new WWW::Myspace;
my $message = new WWW::Myspace::Message( $myspace );
$message->subject("Hi there!");
$message->message("I'm sending you a message!\nIsn't that cool?\n");
$message->add_to_friends( 1 );
$message->friend_ids( $myspace->get_friends );
$message->send_message;The above will send a message to all our myspace friends, stopping if it sends max_count messages or if it receives a CAPTCHA request. Running the same routine again will continue sending where it left off, so if you have a lot of friends you could run it from a cron job.
WWW::Myspace::Message lets you create a message and send it to a group of friends. It implements a counter to avoid tripping WWW::Myspace anti-spam features. If you want to circumvent anti-spam features, this is not the module for you.
EXAMPLES
Since you may have more than 300 people to message, the following script will send a message to all of your friends, and then reset the exclusions file. This allows it to run as a sort of daemon. It will run for days if necessary and stop when finished.
use WWW::Myspace;
use WWW::Myspace::Message;
my $myspace = new WWW::Myspace;
my $message = WWW::Myspace::Message->new( $myspace );
$message->subject("Hi there!");
$message->message("I'm sending you a message!\nIsn't that cool?\n");
$message->friend_ids( $myspace->get_friends );
my $response = "";
# Send our message to our friends until we're done - may take
# several days if we're popular.
while ( $response ne "DONE" ) {
# Send to as many as we can right now. Will stop either
# because it's DONE, it was asked for a CAPTCHA response,
# or because it maxed out the COUNTER.
$response = $message->send_message;
# Wait for a day. (You can probably wait for just 12 hours).
sleep 24*60*60;
}
# We're done sending this message - reset the exclusions file
# completely.
$message->reset_exclusions;Note that because of the log WWW::Myspace::Message keeps, either script could be interrupted and restarted without re-sending to anyone.
The "while" loop above can be replaced with the "send_all" convenience method:
$message->send_all;This is probably the most practical example:
# Set up
use WWW::Myspace;
use WWW::Myspace::Message;
my $myspace = new WWW::Myspace;
# Create the message
my $message = WWW::Myspace::Message->new( $myspace );
$message->subject("Hi there!");
$message->message("I'm sending you a message!\nIsn't that cool?\n");
$message->friend_ids( $myspace->get_friends );
# Send our message to our friends until we're done - may take
# several days if we're popular.
$message->send_all;
# We're done sending this message - reset the exclusions file
# completely.
$message->reset_exclusions;Again, you could kill and restart this script and it'd pick up where it left off (and even incorporiate any changes in your friend list!). Of course if it finished and you restarted it, it'd re-message everyone.
ACCESSOR METHODS
myspace
Sets/retreives the myspace object through which we'll send the message.
subject
Sets/retreives the subject of the message we're to post.
message
Sets/retrieves the message we're to post.
body
Convenience method, same as calling "message". ($message->body("this is my message") reads better sometimes).
add_to_friends
$message->add_to_friends( 1 );If called with 1 true value, HTML code for an "Add to friends" button will be added to the end of the message.
friend_ids
Sets/retreives the list of friend IDs to which we're going to send the message.
$message->friend_ids( 12345, 12347, 123456 ); # Set the list of friends
@friend_ids = $message->friend_ids; # Retreive the list of friendscache_file
WWW::Myspace::Message keeps persistent track of which friends it's messaged to avoid duplicates even across multiple runs. It saves data about its messaging in the file specified in cache_file. Defaults to $myspace->cache_dir/messaged. cache_file will be created if it doesn't exist. If you specify a path, all directories in the path must exist (the module will not create directories for you).
max_count
Defaults to 300. This sets how many messages we'll post before pausing. This is mostly to avoid triggering overuse messages. (You're allowed about 360 per day (possibly per 12 hours period?)).
noisy
Defaults to 0 (not noisy). If set to 1, detailed progress will be output.
html
Defaults to 0. If set to 1, the "noisy" output will contain basic HTML tags so you can send the output to a web browser. Use this if you're displaying using a CGI script.
delay_time
Defaults to 24 hours (24*60*60). Specifies the amount of time to wait between sends when using the send_all method. If set to 0, send_all will return instead of sleeping. This is useful if you want to run a script daily from a crontab for example.
message_delay
Sets the delay between message sends. Defaults to 0, but you probably want to set this to something like 10.
random_delay
If set to 1, delays randomly between 3 seconds and the value of message_delay + 3. Defaults to 0.
paired_arguments
This method is used internally to define the -s and -m flags. If you subclass WWW::Myspace::Message, you can override this method to define more switches. The values of these are loaded into $self->{arguments}. i.e. $self->{arguments}->{'-s'} would give you the subject of the message.
METHODS
new( $myspace )
Initialze and return a new WWW::Myspace::Message object. $myspace is a WWW::Myspace object.
Example
use WWW::Myspace; use WWW::Myspace::Message;
my $myspace = new WWW::Myspace;
my $message = new WWW::Myspace::Message( $myspace );
exclusions
Returns a list of the friends we're not going to send the message to (because we already have). Returns the list in numerical order from lowest to highest. You probably only need this method for communicating with the user.
Example
( @already_messaged ) = $message->exclusions;
messaged
Returns a reference to a hash of friendIDs we've messaged and the status of the attempted messaging. Reads the data from the exclusions cache file if it hasn't already been read.
send_message
Send the message to the friends in the friend_ids list.
The send_message method will automatically skip all friendIDs in the "exclusions" list (see the exclusions method above). It will post until it has posted "max_count" successful posts, or until it receives a CAPTCHA request ("please enter the characters in the image above").
As of version 0.14, send_message will check the Last Login date of the friend_id to which it's sending each message (using Myspace.pm's "last_login" method). If the Last Login is older than 60 days ago, the friendID will be skipped and "FL" will be logged. The friendID will be exluded from future runs to prevent future runs from re-checking a huge list of probably dead accounts.
send_message returns a status string indicating why it stopped:
CAPTCHA if a CAPTCHA image code was requested.
USAGE if we got a message saying we've exceeded our daily usage.
COUNTER if it posted max_count comments and stopped.
FAILURES if it keeps getting errors (more than 50 in a row).
DONE if it posted everywhere it could.send_all
This convenience method implements the while loop script example in the SYNOPSIS section above. If the response is "DONE", it exits. Otherwise, it sleeps for the number of seconds set in "delay_time" and calls send again. It repeats this until it receives "DONE" from the send method. send_all does NOT reset the exclusions file.
Returns the last response code received from send_message. This will always be "DONE" unless delay_time is set to 0 (which is redundant, but exists for scripting convenience as it allows users of your script to set delay_time to 0 if they want to control the messaging, without you having to call a different method - see message_group for example).
EXAMPLE use WWW::Myspace; use WWW::Myspace::Message;
my $myspace = new WWW::Myspace;
my $message = new WWW::Myspace::Message( $myspace );
$message->subject("Hi there!");
$message->message("This is a great message wraught with meaning.");
$message->friend_ids( $myspace->get_friends );
$message->send_all;reset_exclusions
Resets the cache file (which contains previously messaged friendIDs that we'd exclude).
save( filename )
Saves the message to the file specified by "filename".
load( filename )
Loads a message in YAML format (i.e. as saved by the save method) from the file specified by filename.
AUTHOR
Grant Grueninger, <grantg at cpan.org>
BUGS
new method should probably accept a hash of arguments to set all accessable settings (i.e. cache_file). Should also be callable with no arguments.
If cache_file is called with no arguments and cache_file has not been set, it will create the cache dir by invoking the make_cache_dir method of the myspace object. It should probably not create the directory until it's actually writing to the file. Of course, if you don't set cache_file, the first time the method is called would be when writing to the cache file.
If the myspace object hasn't been passed to the WWW::Myspace::Message object yet, and cache_file is called to retreive the default cache_file, the method will croak (as it's trying to call $myspace->make_cache_dir).
If you somehow write to the exclusions file before the exclusions file has been read, $self->messaged will not read the exclusions cache file, and will therefore have an incomplete list. This shouldn't happen in normal operation as the send_message method reads the exclusions file when it's called.
Please report any bugs or feature requests to bug-www-myspace at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=WWW-Myspace. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.
SUPPORT
You can find documentation for this module with the perldoc command.
perldoc WWW::Myspace::MessageYou can also look for information at:
AnnoCPAN: Annotated CPAN documentation
CPAN Ratings
RT: CPAN's request tracker
Search CPAN
ACKNOWLEDGEMENTS
COPYRIGHT & LICENSE
Copyright 2006 Grant Grueninger, all rights reserved.
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.