Thursday, November 5, 2009

Google Account API

This post isn't directly related to PowerShell, but I figured it is better to put it here than nowhere at all. I was looking at my Send-Email and Send-SMS cmdlets the other day, and I figured that the ability to send email or SMS through Gmail and Google Voice might be useful in environments other than PowerShell.

I created a C# class library that provides an API for sending an email through Gmail or an SMS through Google Voice. I added to it a very simple class for dealing with Google Contacts. Google's Contacts API is much more powerful, but I didn't want to add a dependency to my project. This is also partly inspired by my genius little brother, who has developed some similar APIs for Python.

All of the classes in this library use a custom HttpRequester class to make their requests to Google's services. This class keeps track of cookies between requests, handles redirection, and also provides a method for determining the MIME type of a file.

The Gmail class provides a simple way to create an email message and sent it, with full attachment support. Here is the updated code from my Send-Email cmdlet, which, as you can see, is much simpler than the old code:

private void SendGmailMessage()

{

    IntPtr bstr = Marshal.SecureStringToBSTR( googlePassword );

    string plainGooglePassword = Marshal.PtrToStringAuto( bstr );

    Marshal.ZeroFreeBSTR( bstr );

 

    GoogleAccount.Gmail gmailMessage = new GoogleAccount.Gmail( googleUsername, plainGooglePassword );

 

    gmailMessage.OnStatus += new GoogleAccount.Gmail.StatusEventHandler( HandleGmailStatus );

    gmailMessage.OnError += new GoogleAccount.Gmail.ErrorEventHandler( HandleGmailError );

 

    foreach ( string recipient in toArray )

    {

        gmailMessage.To.Add( recipient );

    }

 

    foreach ( string recipient in ccArray )

    {

        gmailMessage.Cc.Add( recipient );

    }

 

    foreach ( string recipient in bccArray )

    {

        gmailMessage.Bcc.Add( recipient );

    }

 

    if ( !string.IsNullOrEmpty( subject ) )

    {

        gmailMessage.Subject = subject;

    }

 

    if ( !string.IsNullOrEmpty( body ) )

    {

        gmailMessage.Body = body;

    }

 

    gmailMessage.BodyIsHtml = bodyIsHtml.IsPresent;

    gmailMessage.Timeout = timeout;

 

    foreach ( FileInfo attachment in inputAttachments )

    {

        gmailMessage.Attachments.Add( attachment );

    }

 

    if ( ShouldProcess( gmailMessage.Subject ) )

    {

        gmailMessage.Send();

    }

}


You might notice the OnStatus and OnError event handlers being set up at the beginning of the function. These are used to report errors and status messages during the several requests necessary to send an email. These handlers are used by the Send-Email cmdlet to provide proper support for the -Verbose parameter.

The SMS class is used in a very similar way. This is how I use it in my Send-SMS cmdlet:

protected override void EndProcessing()

{

    IntPtr bstr = Marshal.SecureStringToBSTR( googlePassword );

    string plainGooglePassword = Marshal.PtrToStringAuto( bstr );

    Marshal.ZeroFreeBSTR( bstr );

 

    GoogleAccount.SMS sms = new GoogleAccount.SMS( googleUsername, plainGooglePassword );

 

    sms.OnStatus += new GoogleAccount.SMS.StatusEventHandler( HandleGoogleVoiceStatus );

    sms.OnError += new GoogleAccount.SMS.ErrorEventHandler( HandleGoogleVoiceError );

 

    sms.Number = this.number;

    sms.Text = this.text;

 

    if ( ShouldProcess( sms.Text ) )

    {

        sms.Send();

    }

}


The Contacts class provides read-only access to each of your Google contacts through a Contact class that has fields for first name, last name, email address, mobile phone, and groups. I create this list by downloading a CSV file and parsing it. Yes, I know I shouldn't parse the CSV data myself, but .NET doesn't have a built-in CSV parser, and I didn't want to add a dependency to a 3rd-party library. It seems to work just fine for its simple purpose.

I wrote a small application to test the Contacts and SMS classes. It is called Mass SMS, and it allows you to choose several contacts to send one SMS message to, a service not provided on the Google Voice site. Here's how it works. First, you log in using your Google username and password:

A pretty self-explanatory dialog for choosing contacts is then displayed. This dialog allows you to filter your contacts by group, such as Family:
Once you have selected the contacts you want to receive your SMS, a dialog is displayed that allows you to specify the message:
The final dialog displays the status of each message as it is being sent:
Pretty simple, but it gets the job done. It was a fun little project to put together, and maybe I will actually use it someday! If you think you might be able to use it, please feel free.