gmail 0.5.0 → 0.6.0

data/.travis.yml

@@ -1,19 +1,19 @@
-rvm:
-  - 1.9.3
-  - 2.0.0
-  - 2.1.5
-  - 2.2.0
-  - rbx
-  - jruby
-
-matrix:
-  allow_failures:
-    - rvm: rbx
-    - rvm: jruby
-
-# http://blog.travis-ci.com/2014-12-17-faster-builds-with-container-based-infrastructure/
-sudo: false
-
-# script:
-#   - bundle exec rspec
-#   - bundle exec rubocop
+rvm:
+  - 1.9.3
+  - 2.0.0
+  - 2.1.5
+  - 2.2.0
+  - rbx
+  - jruby
+
+matrix:
+  allow_failures:
+    - rvm: rbx
+    - rvm: jruby
+
+# http://blog.travis-ci.com/2014-12-17-faster-builds-with-container-based-infrastructure/
+sudo: false
+
+# script:
+#   - bundle exec rspec
+#   - bundle exec rubocop

data/CHANGELOG.md

@@ -1,139 +1,145 @@
-# Gmail Gem Changelog
-
-## Unreleased
-
-* Your change here
-
-
-## 0.5.0 - 2015-01-26
-
-* Migrate primary repo to https://github.com/gmailgem/gmail with new project governance (@johnnyshields, @bootstraponline)
-* Create logo for project (@johnnyshields)
-* Implement IMAP recorder for specs and get all specs passing (@jcarbo)
-* Add Rubocop to porject and fix offenses (@jcarbo)
-* Fix: #connect method not invoking a block (@jcarbo)
-* Support X-GM-RAW (raw Gmail search syntax) in filter query (@bootstraponline)
-* Bugfix: Improperly processing labels containing parentheses (@ryanlchan #82)
-* Add support for localizing labels (@ryanlchan #83)
-* Support for XOAuth2 Client (@KieranP)
-* Improve support for non-english labels and mailboxes (@KieranP)
-* Fix IMAP library patch on Ruby 2 (@bootstraponline, @johnnyshields,  @awakia)
-* Ability to search emails by a UID filter (@KieranP)
-* Add a way to disconnect the IMAP socket (@KieranP)
-* Better support for timezones (@KieranP)
-* Add `emails_in_batches` method (@KieranP)
-* Gmail Message class: Include X-GM-THRID which is the thread id (@jcarbo)
-* Gmail Message class: Include X-GM-MSGID which is a unique, non-changing email identifier (@KieranP)
-* Gmail Message class: Fetch values in bulk and cache them (performance) (@KieranP)
-* Gmail Message class: Pull FLAGS to make #read? and #starred? methods work (@KieranP)
-* Gmail Message class: Don't mark an email as read when accessing the message (@KieranP)
-* Gmail Message class: Reorganisation and cleanup of method definitions (@KieranP)
-* Bugfix: Fix for XOAuth SMTP settings (@molsder #24)
-* Implement Travis CI (@johnnyshields)
-* Remove legacy dependency on MIME gem (@johnnyshields)
-* Upgrade to RSpec 3.1 and remove Mocha dependency (@johnnyshields, @jcarbo #156)
-
-
-## 0.4.2
-
-* Fix issue related to Mail gem version lock (@johnnyshields)
-
-
-## 0.4.1
-
-* n/a
-
-
-## 0.4.0
-
-* Added XOAuth authentication method (Stefano Bernardi, Nicolas Fouché)
-* Separated clients
-* Fixed specs
-
-
-## 0.3.4
-
-* Fixes in mailbox filters shortcuts (Benjamin Bock)
-
-
-## 0.3.3
-
-* Added #expunge to Mailbox (Benjamin Bock)
-* Added more mailbox filters (Benjamin Bock)
-* Added shortcuts for mailbox filters
-* Minor bugfixes
-
-
-## 0.3.2
-
-* Added envelope fetching
-* Minor bugfixes
-
-
-## 0.3.0
-
-* Refactoring
-* Fixed bugs
-* API improvements
-* Better documentation
-* Code cleanup
-* RSpec for everything
-
-
-## 0.1.1 - 2010-05-11
-
-* Added explicit tmail dependency in gemspec
-* Added better README tutorial content
-
-
-## 0.0.9 - 2010-04-17
-
-* Fixed content-transfer-encoding when sending email
-
-
-## 0.0.8 - 2009-12-23
-
-* Fixed attaching a file to an empty message
-
-
-## 0.0.7 - 2009-12-23
-
-* Improved multipart message parsing reliability
-
-
-## 0.0.6 - 2009-12-21
-
-* Fixed multipart parsing for when the boundary is marked in quotes.
-
-
-## 0.0.5 - 2009-12-16
-
-* Fixed IMAP initializer to work with Ruby 1.9's net/imap
-* Better logout depending on the IMAP connection itself
-* Added MIME::Message#text and MIME::Message#html for easier access to an email body
-* Improved the MIME-parsing API slightly
-* Added some tests
-
-
-## 0.0.4 - 2009-11-30
-
-* Added label creation (@justinperkins)
-* Made the gem login automatically when first needed
-* Added an optional block on the Gmail.new object that will login and logout for you
-* Added several search options (@mikker)
-
-
-## 0.0.3 - 2009-11-19
-
-* Fixed MIME::Message#content= for messages without an encoding
-* Added Gmail#new_message
-
-
-## 0.0.2 - 2009-11-18
-
-* Made all of the examples in the README possible
-
-
-## 0.0.1 - 2009-11-18
-
-* Birthday!
+# Gmail Gem Changelog
+
+## Unreleased
+
+* Your change here
+
+## 0.6.0 - 2015-8-24
+
+* [Fix: Labels#localize to not return nil (@afn)](https://github.com/gmailgem/gmail/pull/176)
+* [Fix: label parsing (@yn)](https://github.com/gmailgem/gmail/pull/179)
+* [Feature: Add IDLE support (@alexeymorozov)](https://github.com/gmailgem/gmail/pull/167)
+* [Fix: #deliver to always invoke compose (@kuboon)](https://github.com/gmailgem/gmail/pull/163)
+
+## 0.5.0 - 2015-01-26
+
+* Migrate primary repo to https://github.com/gmailgem/gmail with new project governance (@johnnyshields, @bootstraponline)
+* Create logo for project (@johnnyshields)
+* Implement IMAP recorder for specs and get all specs passing (@jcarbo)
+* Add Rubocop to porject and fix offenses (@jcarbo)
+* Fix: #connect method not invoking a block (@jcarbo)
+* Support X-GM-RAW (raw Gmail search syntax) in filter query (@bootstraponline)
+* Bugfix: Improperly processing labels containing parentheses (@ryanlchan #82)
+* Add support for localizing labels (@ryanlchan #83)
+* Support for XOAuth2 Client (@KieranP)
+* Improve support for non-english labels and mailboxes (@KieranP)
+* Fix IMAP library patch on Ruby 2 (@bootstraponline, @johnnyshields,  @awakia)
+* Ability to search emails by a UID filter (@KieranP)
+* Add a way to disconnect the IMAP socket (@KieranP)
+* Better support for timezones (@KieranP)
+* Add `emails_in_batches` method (@KieranP)
+* Gmail Message class: Include X-GM-THRID which is the thread id (@jcarbo)
+* Gmail Message class: Include X-GM-MSGID which is a unique, non-changing email identifier (@KieranP)
+* Gmail Message class: Fetch values in bulk and cache them (performance) (@KieranP)
+* Gmail Message class: Pull FLAGS to make #read? and #starred? methods work (@KieranP)
+* Gmail Message class: Don't mark an email as read when accessing the message (@KieranP)
+* Gmail Message class: Reorganisation and cleanup of method definitions (@KieranP)
+* Bugfix: Fix for XOAuth SMTP settings (@molsder #24)
+* Implement Travis CI (@johnnyshields)
+* Remove legacy dependency on MIME gem (@johnnyshields)
+* Upgrade to RSpec 3.1 and remove Mocha dependency (@johnnyshields, @jcarbo #156)
+
+
+## 0.4.2
+
+* Fix issue related to Mail gem version lock (@johnnyshields)
+
+
+## 0.4.1
+
+* n/a
+
+
+## 0.4.0
+
+* Added XOAuth authentication method (Stefano Bernardi, Nicolas Fouché)
+* Separated clients
+* Fixed specs
+
+
+## 0.3.4
+
+* Fixes in mailbox filters shortcuts (Benjamin Bock)
+
+
+## 0.3.3
+
+* Added #expunge to Mailbox (Benjamin Bock)
+* Added more mailbox filters (Benjamin Bock)
+* Added shortcuts for mailbox filters
+* Minor bugfixes
+
+
+## 0.3.2
+
+* Added envelope fetching
+* Minor bugfixes
+
+
+## 0.3.0
+
+* Refactoring
+* Fixed bugs
+* API improvements
+* Better documentation
+* Code cleanup
+* RSpec for everything
+
+
+## 0.1.1 - 2010-05-11
+
+* Added explicit tmail dependency in gemspec
+* Added better README tutorial content
+
+
+## 0.0.9 - 2010-04-17
+
+* Fixed content-transfer-encoding when sending email
+
+
+## 0.0.8 - 2009-12-23
+
+* Fixed attaching a file to an empty message
+
+
+## 0.0.7 - 2009-12-23
+
+* Improved multipart message parsing reliability
+
+
+## 0.0.6 - 2009-12-21
+
+* Fixed multipart parsing for when the boundary is marked in quotes.
+
+
+## 0.0.5 - 2009-12-16
+
+* Fixed IMAP initializer to work with Ruby 1.9's net/imap
+* Better logout depending on the IMAP connection itself
+* Added MIME::Message#text and MIME::Message#html for easier access to an email body
+* Improved the MIME-parsing API slightly
+* Added some tests
+
+
+## 0.0.4 - 2009-11-30
+
+* Added label creation (@justinperkins)
+* Made the gem login automatically when first needed
+* Added an optional block on the Gmail.new object that will login and logout for you
+* Added several search options (@mikker)
+
+
+## 0.0.3 - 2009-11-19
+
+* Fixed MIME::Message#content= for messages without an encoding
+* Added Gmail#new_message
+
+
+## 0.0.2 - 2009-11-18
+
+* Made all of the examples in the README possible
+
+
+## 0.0.1 - 2009-11-18
+
+* Birthday!

data/Gemfile

@@ -1,3 +1,3 @@
-source "http://rubygems.org"
-
-gemspec
+source "http://rubygems.org"
+
+gemspec

data/LICENSE

@@ -1,21 +1,21 @@
-Copyrignt (c) 2010 Kriss 'nu7hatch' Kowalik
-Copyright (c) 2009-2010 BehindLogic
-
-Permission is hereby granted, free of charge, to any person obtaining
-a copy of this software and associated documentation files (the
-"Software"), to deal in the Software without restriction, including
-without limitation the rights to use, copy, modify, merge, publish,
-distribute, sublicense, and/or sell copies of the Software, and to
-permit persons to whom the Software is furnished to do so, subject to
-the following conditions:
-
-The above copyright notice and this permission notice shall be
-included in all copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
-EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
-MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
-NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
-LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
-OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
-WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+Copyrignt (c) 2010 Kriss 'nu7hatch' Kowalik
+Copyright (c) 2009-2010 BehindLogic
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -1,354 +1,355 @@
-<img alt="Gmail for Ruby" src="https://cloud.githubusercontent.com/assets/27655/5792399/fd5d076e-9f59-11e4-826c-22c311e38356.png">
-
-[![Build Status](https://travis-ci.org/gmailgem/gmail.svg)](https://travis-ci.org/gmailgem/gmail)
-[![Code Climate](https://codeclimate.com/github/gmailgem/gmail.svg)](https://codeclimate.com/github/gmailgem/gmail)
-[![Gem Version](https://badge.fury.io/rb/gmail.svg)](http://badge.fury.io/rb/gmail)
-
-A Rubyesque interface to Google's Gmail, with all the tools you'll need. Search, 
-read and send multipart emails, archive, mark as read/unread, delete emails, 
-and manage labels.
-
-It's based on Daniel Parker's ruby-gmail gem. This version has more friendly
-API, is well tested, better documented and have many other improvements.
-
-## Installation
-
-You can install it easy using rubygems:
-
-    sudo gem install gmail
-    
-Or install it manually:
-
-    git clone git://github.com/gmailgem/gmail.git
-    cd gmail
-    rake install
-
-gmail gem has the following dependencies (with Bundler all will be installed automatically):
-
-* mail
-* gmail_xoauth
-
-## Version Support
-
-* Ruby 2.0.0+ is supported
-* Ruby 1.9.3 is supported but deprecated and is planned to be dropped from gmail v0.6.0
-* Ruby 1.8.7 users should use gmail v0.4.1
-
-## Features
-
-* Search emails
-* Read emails (handles attachments)
-* Emails: label, archive, delete, mark as read/unread/spam, star
-* Manage labels
-* Create and send multipart email messages in plaintext and/or html, with inline 
-  images and attachments
-* Utilizes Gmail's IMAP & SMTP, MIME-type detection and parses and generates 
-  MIME properly.
-
-## Basic usage
-
-First of all require the `gmail` library.
-
-```ruby
-require 'gmail'
-```
-
-### Authenticating gmail sessions
-
-This will let you automatically log in to your account. 
-
-```ruby
-gmail = Gmail.connect(username, password)
-# play with your gmail...
-gmail.logout
-```
-
-If you pass a block, the session will be passed into the block, and the session 
-will be logged out after the block is executed.
-
-```ruby
-Gmail.connect(username, password) do |gmail|
-  # play with your gmail...
-end
-```
-
-Examples above are "quiet", it means that it will not raise any errors when 
-session couldn't be started (eg. because of connection error or invalid 
-authorization data). You can use connection which handles errors raising:
-
-```ruby
-Gmail.connect!(username, password)
-Gmail.connect!(username, password) {|gmail| ... play with gmail ... }
-```
-
-You can also check if you are logged in at any time:
-
-```ruby
-Gmail.connect(username, password) do |gmail|
-  gmail.logged_in?
-end
-```
-
-### XOAuth authentication
-
-From v0.4.0 it's possible to authenticate with your Gmail account using XOAuth
-method. It's very simple:
-
-```ruby
-gmail = Gmail.connect(:xoauth, "email@domain.com", 
-  :token           => 'TOKEN',
-  :secret          => 'TOKEN_SECRET',
-  :consumer_key    => 'CONSUMER_KEY',
-  :consumer_secret => 'CONSUMER_SECRET'
-)
-```
-    
-For more information check out the [gmail_xoauth](https://github.com/nfo/gmail_xoauth)
-gem from Nicolas Fouché.
-
-### Counting and gathering emails
-    
-Get counts for messages in the inbox:
-
-```ruby
-gmail.inbox.count
-gmail.inbox.count(:unread)
-gmail.inbox.count(:read)
-```
-
-Count with some criteria:
-
-```ruby
-gmail.inbox.count(:after => Date.parse("2010-02-20"), :before => Date.parse("2010-03-20"))
-gmail.inbox.count(:on => Date.parse("2010-04-15"))
-gmail.inbox.count(:from => "myfriend@gmail.com")
-gmail.inbox.count(:to => "directlytome@gmail.com")
-```
-
-Combine flags and options:
-
-```ruby
-gmail.inbox.count(:unread, :from => "myboss@gmail.com")
-```
-
-Browsing labeled emails is similar to work with inbox.
-
-```ruby
-gmail.mailbox('Urgent').count
-```
-
-Getting messages works the same way as counting: Remember that every message in a 
-conversation/thread will come as a separate message.
-
-```ruby
-gmail.inbox.emails(:unread, :before => Date.parse("2010-04-20"), :from => "myboss@gmail.com")
-```
-
-The [gm option](https://developers.google.com/gmail/imap_extensions?csw=1#extension_of_the_search_command_x-gm-raw) enables use of the Gmail search syntax.
-
-```ruby
-gmail.inbox.emails(gm: '"testing"')
-```
-
-You can use also one of aliases:
-
-```ruby
-gmail.inbox.find(...)
-gmail.inbox.search(...)
-gmail.inbox.mails(...)
-```
-
-Also you can manipulate each message using block style:
-
-```ruby
-gmail.inbox.find(:unread).each do |email|
-  email.read!
-end
-```
-
-### Working with emails!
-
-Any news older than 4-20, mark as read and archive it:
-
-```ruby
-gmail.inbox.find(:before => Date.parse("2010-04-20"), :from => "news@nbcnews.com").each do |email|
-  email.read! # can also unread!, spam! or star!
-  email.archive!
-end
-```
-
-Delete emails from X:
-
-```ruby
-gmail.inbox.find(:from => "x-fiance@gmail.com").each do |email|
-  email.delete!
-end
-```
-
-Save all attachments in the "Faxes" label to a local folder (uses functionality from `Mail` gem):
-
-```ruby
-folder = Dir.pwd # for example
-gmail.mailbox("Faxes").emails.each do |email|
-  email.message.attachments.each do |f|
-    File.write(File.join(folder, f.filename), f.body.decoded)
-  end
-end
-```
-     
-You can use also `#label` method instead of `#mailbox`: 
-
-```ruby
-gmail.label("Faxes").emails {|email| ... }
-```
-
-Save just the first attachment from the newest unread email (assuming pdf):
-
-```ruby
-email = gmail.inbox.find(:unread).first
-email.attachments[0].save_to_file("/path/to/location")
-```
-
-Add a label to a message:
-
-```ruby
-email.label("Faxes")
-```
-
-Example above will raise error when you don't have the `Faxes` label. You can 
-avoid this using:
-
-```ruby
-email.label!("Faxes") # The `Faxes` label will be automatically created now
-```
-
-You can also move message to a label/mailbox:
-
-```ruby 
-email.move_to("Faxes")
-email.move_to!("NewLabel")
-```
-
-There is also few shortcuts to mark messages quickly:
-
-```ruby
-email.read!
-email.unread!
-email.spam!
-email.star!
-email.unstar!
-```
-
-### Managing labels
-
-With Gmail gem you can also manage your labels. You can get list of defined 
-labels:
-
-```ruby
-gmail.labels.all
-```
-
-Create new label:
-
-```ruby  
-gmail.labels.new("Urgent")
-gmail.labels.add("AnotherOne")
-```
-
-Remove labels:
-
-```ruby
-gmail.labels.delete("Urgent")
-```
-
-Or check if given label exists:
-
-```ruby
-gmail.labels.exists?("Urgent")     # => false
-gmail.labels.exists?("AnotherOne") # => true
-```
-
-Localize label names using the LIST special-use extension flags,
-:Inbox, :All, :Drafts, :Sent, :Trash, :Important, :Junk, and :Flagged
-
-```ruby
-gmail.labels.localize(:all) # => "[Gmail]\All Mail"
-                            # => "[Google Mail]\All Mail"
-```
-
-### Composing and sending emails
-
-Creating emails now uses the amazing [Mail](http://rubygems.org/gems/mail) rubygem. 
-See its [documentation here](http://github.com/mikel/mail). The Ruby Gmail will 
-automatically configure your Mail emails to be sent via your Gmail account's SMTP, 
-so they will be in your Gmail's "Sent" folder. Also, no need to specify the "From" 
-email either, because ruby-gmail will set it for you.
-
-```ruby
-gmail.deliver do
-  to "email@example.com"
-  subject "Having fun in Puerto Rico!"
-  text_part do
-    body "Text of plaintext message."
-  end
-  html_part do
-    content_type 'text/html; charset=UTF-8'
-    body "<p>Text of <em>html</em> message.</p>"
-  end
-  add_file "/path/to/some_image.jpg"
-end
-```
-
-Or, compose the message first and send it later
-
-```ruby
-email = gmail.compose do
-  to "email@example.com"
-  subject "Having fun in Puerto Rico!"
-  body "Spent the day on the road..."
-end
-email.deliver! # or: gmail.deliver(email)
-```
-
-## Troubleshooting
-
-If you are having trouble connecting to Gmail:
-* Please ensure your account is verified
-* In [Gmail Security Settings](https://www.google.com/settings/security), enable access for less secure applications.
-* Read [this support answer re: suspicious activity](https://support.google.com/mail/answer/78754) and try things like entering a captcha.
-
-## Note on Patches/Pull Requests
- 
-* 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.
-
-## Authors
-
-#### Core Team
-
-This project follows on Open Governance model. The Core Team is responsible for technical guidance, reviewing/merging PRs, and releases.
-
-* Jeff Carbonella - [@jcarbo](https://github.com/jcarbo)
-* Johnny Shields - [@johnnyshields](https://github.com/johnnyshields)
-* Alexandre Loureiro Solleiro - [@webcracy](https://github.com/webcracy)
-* Justin Grevitch - [@jgrevich](https://github.com/jgrevich)
-* [@bootstraponline](https://github.com/bootstraponline)
-
-#### Legacy Contributors
-
-* Kriss Kowalik - [@nu7hatch](https://github.com/nu7hatch)
-* Daniel Parker - [@dcparker](https://github.com/dcparker)
-* Refer to [CHANGELOG](https://github.com/gmailgem/gmail/blob/master/CHANGELOG.md) for individual contributions
-
-## Copyright
-
-* Copyright (c) 2015 GmailGem team
-* Copyright (c) 2010-2014 Kriss 'nu7hatch' Kowalik
-* Copyright (c) 2009-2010 BehindLogic
-
-Licensed under the MIT license. See [LICENSE](https://github.com/gmailgem/gmail/blob/master/LICENSE) for details.
+<img alt="Gmail for Ruby" src="https://cloud.githubusercontent.com/assets/27655/5792399/fd5d076e-9f59-11e4-826c-22c311e38356.png">
+
+[![Build Status](https://travis-ci.org/gmailgem/gmail.svg)](https://travis-ci.org/gmailgem/gmail)
+[![Code Climate](https://codeclimate.com/github/gmailgem/gmail.svg)](https://codeclimate.com/github/gmailgem/gmail)
+[![Gem Version](https://badge.fury.io/rb/gmail.svg)](http://badge.fury.io/rb/gmail)
+
+A Rubyesque interface to Google's Gmail, with all the tools you'll need. Search, 
+read and send multipart emails, archive, mark as read/unread, delete emails, 
+and manage labels.
+
+It's based on Daniel Parker's ruby-gmail gem. This version has more friendly
+API, is well tested, better documented and have many other improvements.
+
+## Installation
+
+You can install it easy using rubygems:
+
+    sudo gem install gmail
+    
+Or install it manually:
+
+    git clone git://github.com/gmailgem/gmail.git
+    cd gmail
+    rake install
+
+gmail gem has the following dependencies (with Bundler all will be installed automatically):
+
+* mail
+* gmail_xoauth
+
+## Version Support
+
+* Ruby 2.0.0+ is supported
+* Ruby 1.9.3 is supported but deprecated and is planned to be dropped from gmail v0.6.0
+* Ruby 1.8.7 users should use gmail v0.4.1
+
+## Features
+
+* Search emails
+* Read emails (handles attachments)
+* Emails: label, archive, delete, mark as read/unread/spam, star
+* Manage labels
+* Create and send multipart email messages in plaintext and/or html, with inline 
+  images and attachments
+* Utilizes Gmail's IMAP & SMTP, MIME-type detection and parses and generates 
+  MIME properly.
+
+## Basic usage
+
+First of all require the `gmail` library.
+
+```ruby
+require 'gmail'
+```
+
+### Authenticating gmail sessions
+
+This will let you automatically log in to your account. 
+
+```ruby
+gmail = Gmail.connect(username, password)
+# play with your gmail...
+gmail.logout
+```
+
+If you pass a block, the session will be passed into the block, and the session 
+will be logged out after the block is executed.
+
+```ruby
+Gmail.connect(username, password) do |gmail|
+  # play with your gmail...
+end
+```
+
+Examples above are "quiet", it means that it will not raise any errors when 
+session couldn't be started (eg. because of connection error or invalid 
+authorization data). You can use connection which handles errors raising:
+
+```ruby
+Gmail.connect!(username, password)
+Gmail.connect!(username, password) {|gmail| ... play with gmail ... }
+```
+
+You can also check if you are logged in at any time:
+
+```ruby
+Gmail.connect(username, password) do |gmail|
+  gmail.logged_in?
+end
+```
+
+### XOAuth authentication
+
+From v0.4.0 it's possible to authenticate with your Gmail account using XOAuth
+method. It's very simple:
+
+```ruby
+gmail = Gmail.connect(:xoauth, "email@domain.com", 
+  :token           => 'TOKEN',
+  :secret          => 'TOKEN_SECRET',
+  :consumer_key    => 'CONSUMER_KEY',
+  :consumer_secret => 'CONSUMER_SECRET'
+)
+```
+    
+For more information check out the [gmail_xoauth](https://github.com/nfo/gmail_xoauth)
+gem from Nicolas Fouché.
+
+### Counting and gathering emails
+    
+Get counts for messages in the inbox:
+
+```ruby
+gmail.inbox.count
+gmail.inbox.count(:unread)
+gmail.inbox.count(:read)
+```
+
+Count with some criteria:
+
+```ruby
+gmail.inbox.count(:after => Date.parse("2010-02-20"), :before => Date.parse("2010-03-20"))
+gmail.inbox.count(:on => Date.parse("2010-04-15"))
+gmail.inbox.count(:from => "myfriend@gmail.com")
+gmail.inbox.count(:to => "directlytome@gmail.com")
+```
+
+Combine flags and options:
+
+```ruby
+gmail.inbox.count(:unread, :from => "myboss@gmail.com")
+```
+
+Browsing labeled emails is similar to work with inbox.
+
+```ruby
+gmail.mailbox('Urgent').count
+```
+
+Getting messages works the same way as counting: Remember that every message in a 
+conversation/thread will come as a separate message.
+
+```ruby
+gmail.inbox.emails(:unread, :before => Date.parse("2010-04-20"), :from => "myboss@gmail.com")
+```
+
+The [gm option](https://developers.google.com/gmail/imap_extensions?csw=1#extension_of_the_search_command_x-gm-raw) enables use of the Gmail search syntax.
+
+```ruby
+gmail.inbox.emails(gm: '"testing"')
+```
+
+You can use also one of aliases:
+
+```ruby
+gmail.inbox.find(...)
+gmail.inbox.search(...)
+gmail.inbox.mails(...)
+```
+
+Also you can manipulate each message using block style:
+
+```ruby
+gmail.inbox.find(:unread).each do |email|
+  email.read!
+end
+```
+
+### Working with emails!
+
+Any news older than 4-20, mark as read and archive it:
+
+```ruby
+gmail.inbox.find(:before => Date.parse("2010-04-20"), :from => "news@nbcnews.com").each do |email|
+  email.read! # can also unread!, spam! or star!
+  email.archive!
+end
+```
+
+Delete emails from X:
+
+```ruby
+gmail.inbox.find(:from => "x-fiance@gmail.com").each do |email|
+  email.delete!
+end
+```
+
+Save all attachments in the "Faxes" label to a local folder (uses functionality from `Mail` gem):
+
+```ruby
+folder = Dir.pwd # for example
+gmail.mailbox("Faxes").emails.each do |email|
+  email.message.attachments.each do |f|
+    File.write(File.join(folder, f.filename), f.body.decoded)
+  end
+end
+```
+     
+You can use also `#label` method instead of `#mailbox`: 
+
+```ruby
+gmail.label("Faxes").emails {|email| ... }
+```
+
+Save just the first attachment from the newest unread email (assuming pdf):
+
+```ruby
+email = gmail.inbox.find(:unread).first
+email.attachments[0].save_to_file("/path/to/location")
+```
+
+Add a label to a message:
+
+```ruby
+email.label("Faxes")
+```
+
+Example above will raise error when you don't have the `Faxes` label. You can 
+avoid this using:
+
+```ruby
+email.label!("Faxes") # The `Faxes` label will be automatically created now
+```
+
+You can also move message to a label/mailbox:
+
+```ruby 
+email.move_to("Faxes")
+email.move_to!("NewLabel")
+```
+
+There is also few shortcuts to mark messages quickly:
+
+```ruby
+email.read!
+email.unread!
+email.spam!
+email.star!
+email.unstar!
+```
+
+### Managing labels
+
+With Gmail gem you can also manage your labels. You can get list of defined 
+labels:
+
+```ruby
+gmail.labels.all
+```
+
+Create new label:
+
+```ruby  
+gmail.labels.new("Urgent")
+gmail.labels.add("AnotherOne")
+```
+
+Remove labels:
+
+```ruby
+gmail.labels.delete("Urgent")
+```
+
+Or check if given label exists:
+
+```ruby
+gmail.labels.exists?("Urgent")     # => false
+gmail.labels.exists?("AnotherOne") # => true
+```
+
+Localize label names using the LIST special-use extension flags,
+:Inbox, :All, :Drafts, :Sent, :Trash, :Important, :Junk, and :Flagged
+
+```ruby
+gmail.labels.localize(:all) # => "[Gmail]\All Mail"
+                            # => "[Google Mail]\All Mail"
+```
+
+### Composing and sending emails
+
+Creating emails now uses the amazing [Mail](http://rubygems.org/gems/mail) rubygem. 
+See its [documentation here](http://github.com/mikel/mail). The Ruby Gmail will 
+automatically configure your Mail emails to be sent via your Gmail account's SMTP, 
+so they will be in your Gmail's "Sent" folder. Also, no need to specify the "From" 
+email either, because ruby-gmail will set it for you.
+
+```ruby
+gmail.deliver do
+  to "email@example.com"
+  subject "Having fun in Puerto Rico!"
+  text_part do
+    body "Text of plaintext message."
+  end
+  html_part do
+    content_type 'text/html; charset=UTF-8'
+    body "<p>Text of <em>html</em> message.</p>"
+  end
+  add_file "/path/to/some_image.jpg"
+end
+```
+
+Or, compose the message first and send it later
+
+```ruby
+email = gmail.compose do
+  to "email@example.com"
+  subject "Having fun in Puerto Rico!"
+  body "Spent the day on the road..."
+end
+email.deliver! # or: gmail.deliver(email)
+```
+
+## Troubleshooting
+
+If you are having trouble connecting to Gmail:
+* Please ensure your account is verified
+* In [Gmail Security Settings](https://www.google.com/settings/security), enable access for less secure applications.
+* Read [this support answer re: suspicious activity](https://support.google.com/mail/answer/78754) and try things like entering a captcha.
+
+## Note on Patches/Pull Requests
+ 
+* 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.
+
+## Authors
+
+#### Core Team
+
+This project follows on Open Governance model. The Core Team is responsible for technical guidance, reviewing/merging PRs, and releases.
+
+* Jeff Carbonella - [@jcarbo](https://github.com/jcarbo)
+* Johnny Shields - [@johnnyshields](https://github.com/johnnyshields)
+* Alexandre Loureiro Solleiro - [@webcracy](https://github.com/webcracy)
+* Justin Grevich - [@jgrevich](https://github.com/jgrevich)
+* [@bootstraponline](https://github.com/bootstraponline)
+* Nathan Herald - [@myobie](https://github.com/myobie)
+
+#### Legacy Contributors
+
+* Kriss Kowalik - [@nu7hatch](https://github.com/nu7hatch)
+* Daniel Parker - [@dcparker](https://github.com/dcparker)
+* Refer to [CHANGELOG](https://github.com/gmailgem/gmail/blob/master/CHANGELOG.md) for individual contributions
+
+## Copyright
+
+* Copyright (c) 2015 GmailGem team
+* Copyright (c) 2010-2014 Kriss 'nu7hatch' Kowalik
+* Copyright (c) 2009-2010 BehindLogic
+
+Licensed under the MIT license. See [LICENSE](https://github.com/gmailgem/gmail/blob/master/LICENSE) for details.