Month: February 2009

Google has released an API for almost all of their products including maps, feedburner and gadgets. However one of the API’s which every developer would have loved to make use of is “Google Mail API” which is still missing (available for premium google apps user only). Here in this post I would demonstrate how one can programatically control his/her google mails using JAXL without being a premium user of google mail account.

For those who have landed on this post straight and have little knowledge about what JAXL is “JAXL stands for Jabber XMPP Library and for fun you may call it Just Another XMPP Library. It is written in PHP and can be downloaded from http://code.google.com/p/jaxl“. To know more about JAXL, read the introductory post here. If you want to dig deep and know how JAXL works, read the gtalk case study here. Finally, after reading this post you may also want to check how you can fetch any social networking feed right into your gtalk messenger using JAXL.

Version 1.0.4 of JAXL included support for “Gmail Notification Extension of XMPP“. If you are a daily Gtalk user like me, then you have surely seen this extension in action. Just recall Gtalk notifying you of a new mail in your inbox, through a pop-up in the bottom right corner. Also those who see this in action everyday will agree with me that this notification comes even before the mail has actually appeared in you inbox. Simply because of the PUSH technology used by XMPP protocol.

So why would you in first place be interested in accessing your google mails programatically. A quick thought on this brings me to the following real life scenarios:

• Suppose your are out of vacation and you want to set a custom auto-reply message for your family and friends, while you want to set a general out-of-office message for your colleagues. The limitation in gmail is that you can’t really do this. Further in this post, I will show you how can you achieve this using JAXL.
• Suppose you are a google app user and your company has organized an online programming contest. Further you want to mail each question to the contestants only if they has answered the previous question. JAXL provide you a way to access key information about your incoming mails like: sender email id, subject, number of threads in the mail, time at which mail was sent, mail url and mail snippet. Which is enough for you to code a bot which can check for incoming mail and then send in next question to the contestant who sent this mail
Further there can be a thousand use cases where you would you like to have such a control over you google mails but before discussing them, lets see a demonstration on how can we use JAXL to achieve this.

Sending Custom Auto-Reply Mails using JAXL
Along with extendable functions like eventMessage() and eventPresence(), JAXL’s latest version now also provide another extendable function called eventNewEMail(). So everytime you receive a new mail(s) in your google account, the control is passed to this function along with all informations about the incoming mails.

Various data passed to this function are:

• $total: Tells you about total number of unread mails.
• $thread: The thread id of all the unread threads. Note: In Gmail you have threads in your inbox which can contain more than a single mail.
• $url: The mail.google.com url for the new mail
• $participation: This can be 0, 1 or 2. 0 indicates that you have not participated, 1 indicates that you are one of the many recipients and 2 indicates that you are the sole recipient for messages in this thread
• $message: The number of messages in the thread. For instance you can have more than one unread mail in a thread.
• $date: A timestamp of the most recent unread message, in milliseconds since the UNIX epoch
• $senders: Email Id of all the senders in the current thread
• $labels: Label if any to which this mail thread belongs to
• $subject: The subject of the mail threads
• $snippet: The mail snippet of the incoming mail

So thats a lot of information really, with which we can automate things to a certain extent. Lets see how I use it to send custom auto-reply mails when I am out on vacation. Here is the extendable jaxl class for gmail:

jaxl4gmail.class.php (Download)

  /* Include PHP Mailer Class */
  include_once("class.phpmailer.php");

  /* Include XMPP Class */
  include_once("xmpp.class.php");

  class JAXL extends XMPP {

    /* Define custom mail groups */
    var $family = array("[email protected]","[email protected]");
    var $colleague = array("[email protected]","[email protected]");

    /* Define custom mail subject and message */
    var $familySubject = "Hi, Will get back to you";
    var $familyMessage = "Hey, I am currently out on vacation at my grannies house in Delhi. I will return back home by next monday.
Reach out to me at +91-987654321.

With Love,
Abhinav Singh";

    /* Define custom mail subject and message */
    var $colleagueSubject = "[Auto-Reply] Out of Office";
    var $colleagueMessage = "Hi, I am on vacation in my village with very limited access to internet and phone. I will return back home by next monday.

Regards,
Abhinav Singh";

    function eventMessage($fromJid, $content, $offline = FALSE) {

    }

    function eventPresence($fromJid, $status, $photo) {

    }

    function eventNewEMail($total,$thread,$url,$participation,$messages,$date,$senders,$labels,$subject,$snippet) {
      // We only want to send auto-reply message to latest sender
      $sender = $senders[0];

      // Check if the user lie in any category, and send appropriate mail
      if(in_array($sender["address"],$this->family)) {
        $mail = new PHPMailer();
        $mail->From = "[email protected]";
        $mail->FromName = "Your Name";
        $mail->Subject = $this->familySubject;
        $mail->MsgHTML($this->familyMessage."

Powered by Jaxl http://code.google.com/p/jaxl");
        $mail->IsHTML(true);
        $mail->AddAddress($sender["address"],$sender["name"]);

        if(!$mail->Send()) $this->logger->logger("Error occured while sending mail to ".$sender["address"]);
        else $this->logger->logger("Mail sent successfully to ".$sender["address"]);
      }
      else if(in_array($sender["address"],$this->colleague)) {
        $mail = new PHPMailer();
        $mail->From = "[email protected]";
        $mail->FromName = "Your Name";
        $mail->Subject = $this->colleagueSubject;
        $mail->MsgHTML($this->colleagueMessage."

Powered by Jaxl http://code.google.com/p/jaxl");
        $mail->IsHTML(true);
        $mail->AddAddress($sender["address"],$sender["name"]);

        if(!$mail->Send()) $this->logger->logger("Error occured while sending mail to ".$sender["address"]);
        else $this->logger->logger("Mail sent successfully to ".$sender["address"]);
      }
      else {
        // Do nothing, will handle later on
        $this->logger->logger("No handler for this email id...");
      }
    }

    function setStatus() {
      print "Setting Status...n";
      $this->sendStatus("Available");
      print "Requesting new mails...n";
      $this->getNewEMail();
      print "Donen";
    }

  }

The only variables you would like to change in above class are:

1. $family : An array of email id of your family member
2. $colleague : An array of email id of your colleagues
3. $familySubject : Subject with which you want to send mails to your family members
4. $familyMessage : Mail message which you want to send to you family
5. $colleagueSubject : Subject with which you want to send mails to your colleagues
6. $colleagueMessage : Mail message which you want to send to you colleagues

For further customization, you may want to add more groups and their respective subjects and messages.

Further you may want to create your own custom bots using JAXL for one of the other use case described above. Join official JAXL Google Group for future updates and enhancements.

Do let me know if you build any custom bot using JAXL, I will be more than happy to list your bot on official JAXL google code page.

Enjoy!