gmail_xoauth

Get access to Gmail IMAP and SMTP via OAuth2 and OAuth 1.0a, using the standard Ruby Net libraries.

The gem supports 3-legged OAuth, and 2-legged OAuth for Google Apps Business or Education account owners.

$ gem install gmail_xoauth

You can generate and validate your OAuth 2.0 tokens thanks to the oauth2.py tool.

Create your API project in the Google APIs console, from the menu "APIs and auth > Credentials". Click on "Create new Client ID", choose "Installed Application" and "Other".

Then go to the menu "APIs and auth > Consent screen" and enter an email address and product name.

$ python oauth2.py --generate_oauth2_token --client_id=423906513574-o9v6kqt89lefrbfv1f3394u9rebfgv6n.apps.googleusercontent.com --client_secret=5SfdvZsYagblukE5VAhERjxZ

require 'gmail_xoauth'
imap = Net::IMAP.new('imap.gmail.com', 993, usessl = true, certs = nil, verify = false)
imap.authenticate('XOAUTH2', 'myemail@gmail.com', my_oauth2_token)
messages_count = imap.status('INBOX', ['MESSAGES'])['MESSAGES']
puts "Seeing #{messages_count} messages in INBOX"

require 'gmail_xoauth'
smtp = Net::SMTP.new('smtp.gmail.com', 587)
smtp.enable_starttls_auto
smtp.start('gmail.com', 'myemail@gmail.com', my_oauth2_token, :xoauth2)
smtp.finish

== OAuth 1.0 has been officially deprecated as of April 20, 2012. ==

For testing, you can generate and validate your OAuth tokens thanks to the awesome xoauth.py tool.

$ python xoauth.py --generate_oauth_token --user=myemail@gmail.com

Or if you want some webapp code, check the gmail-oauth-sinatra project.

For your tests, Gmail allows to set 'anonymous' as the consumer key and secret.

require 'gmail_xoauth'
imap = Net::IMAP.new('imap.gmail.com', 993, usessl = true, certs = nil, verify = false)
imap.authenticate('XOAUTH', 'myemail@gmail.com',
  :consumer_key => 'anonymous',
  :consumer_secret => 'anonymous',
  :token => '4/nM2QAaunKUINb4RrXPC55F-mix_k',
  :token_secret => '41r18IyXjIvuyabS/NDyW6+m'
)
messages_count = imap.status('INBOX', ['MESSAGES'])['MESSAGES']
puts "Seeing #{messages_count} messages in INBOX"

Note that the Net::IMAP#login method does not use support custom authenticators, so you have to use the Net::IMAP#authenticate method.

require 'gmail_xoauth'
imap = Net::IMAP.new('imap.gmail.com', 993, usessl = true, certs = nil, verify = false)
imap.authenticate('XOAUTH', 'myemail@mydomain.com',
  :two_legged => true,
  :consumer_key => 'a',
  :consumer_secret => 'b'
)

For your tests, Gmail allows to set 'anonymous' as the consumer key and secret.

require 'gmail_xoauth'
smtp = Net::SMTP.new('smtp.gmail.com', 587)
smtp.enable_starttls_auto
secret = {
  :consumer_key => 'anonymous',
  :consumer_secret => 'anonymous',
  :token => '4/nM2QAaunKUINb4RrXPC55F-mix_k',
  :token_secret => '41r18IyXjIvuyabS/NDyW6+m'
}
smtp.start('gmail.com', 'myemail@gmail.com', secret, :xoauth)
smtp.finish

Note that Net::SMTP#enable_starttls_auto is not defined in Ruby 1.8.6.

require 'gmail_xoauth'
smtp = Net::SMTP.new('smtp.gmail.com', 587)
smtp.enable_starttls_auto
secret = {
	:two_legged => true,
  :consumer_key => 'a',
  :consumer_secret => 'b'
}
smtp.start('gmail.com', 'myemail@mydomain.com', secret, :xoauth)
smtp.finish

Tested on Ruby MRI 1.8.6, 1.8.7, 1.9.x and 2.1.x. Feel free to send me a message if you tested this code with other implementations of Ruby.

The only external dependency is the oauth gem.

• 0.4.3 Maintenance: Use Net::IMAP::SASL.add_authenticator to silence deprecation warning, thanks to mantas
• 0.4.2 SMTP: on 3xx response to 'AUTH XOAUTH2' send CR-LF to get actual error, thanks to rafalyesware
• 0.4.1 XOAUTH2 support, thanks to glongman
• 0.3.2 New email for the maintainer
• 0.3.1 2-legged OAuth support confirmed by BobDohnal
• 0.3.0 Experimental 2-legged OAuth support, thanks to wojciech
• 0.2.0 SMTP support
• 0.1.0 Initial release with IMAP support and 3-legged OAuth

• Fork the project.
• Make your feature addition or bug fix.
• Add tests for it. This is important so I don't break it in a future version unintentionally.
• Commit, do not mess with rakefile, version, or history. (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
• Send me a pull request. Bonus points for topic branches.

https://nicolasfouche.com

See LICENSE for details.