/README.markdown

  1# Notice
  2I am looking for for a new project owner for this project.  Please contact me if you are interested in maintaining this 
  3project or being added as a contributor.  
  4
  5Sincerely,  
  6[Joshavne Potter](mailto:yourtech@gmail.com?subject=ruby-gmail%20gem%20support)
  7
  8# ruby-gmail
  9
 10* Homepage: [http://dcparker.github.com/ruby-gmail/](http://dcparker.github.com/ruby-gmail/)
 11* Code: [http://github.com/dcparker/ruby-gmail](http://github.com/dcparker/ruby-gmail)
 12* Gem: [http://gemcutter.org/gems/ruby-gmail](http://gemcutter.org/gems/ruby-gmail)
 13
 14## Author(s)
 15
 16* Daniel Parker of BehindLogic.com
 17
 18Extra thanks for specific feature contributions from:
 19
 20  * [Justin Perkins](http://github.com/justinperkins)
 21  * [Mikkel Malmberg](http://github.com/mikker)
 22  * [Julien Blanchard](http://github.com/julienXX)
 23  * [Federico Galassi](http://github.com/fgalassi)
 24
 25## Description
 26
 27A Rubyesque interface to Gmail, with all the tools you'll need. Search, read and send multipart emails; archive, mark as read/unread, delete emails; and manage labels.
 28
 29## Features
 30
 31* Search emails
 32* Read emails (handles attachments)
 33* Emails: Label, archive, delete, mark as read/unread/spam
 34* Create and delete labels
 35* Create and send multipart email messages in plaintext and/or html, with inline images and attachments
 36* Utilizes Gmail's IMAP & SMTP, MIME-type detection and parses and generates MIME properly.
 37
 38## Problems:
 39
 40* May not correctly read malformed MIME messages. This could possibly be corrected by having IMAP parse the MIME structure.
 41* Cannot grab the plain or html message without also grabbing attachments. It might be nice to lazy-[down]load attachments.
 42
 43## Example Code:
 44
 45### 1) Require gmail
 46
 47    require 'gmail'
 48    
 49### 2) Start an authenticated gmail session
 50
 51    #    If you pass a block, the session will be passed into the block,
 52    #    and the session will be logged out after the block is executed.
 53    gmail = Gmail.new(username, password)
 54    # ...do things...
 55    gmail.logout
 56
 57    Gmail.new(username, password) do |gmail|
 58      # ...do things...
 59    end
 60
 61### 3) Count and gather emails!
 62    
 63    # Get counts for messages in the inbox
 64    gmail.inbox.count
 65    gmail.inbox.count(:unread)
 66    gmail.inbox.count(:read)
 67
 68    # Count with some criteria
 69    gmail.inbox.count(:after => Date.parse("2010-02-20"), :before => Date.parse("2010-03-20"))
 70    gmail.inbox.count(:on => Date.parse("2010-04-15"))
 71    gmail.inbox.count(:from => "myfriend@gmail.com")
 72    gmail.inbox.count(:to => "directlytome@gmail.com")
 73
 74    # Combine flags and options
 75    gmail.inbox.count(:unread, :from => "myboss@gmail.com")
 76    
 77    # Labels work the same way as inbox
 78    gmail.mailbox('Urgent').count
 79    
 80    # Getting messages works the same way as counting: optional flag, and optional arguments
 81    # Remember that every message in a conversation/thread will come as a separate message.
 82    gmail.inbox.emails(:unread, :before => Date.parse("2010-04-20"), :from => "myboss@gmail.com")
 83
 84    # Get messages without marking them as read on the server.
 85    gmail.peek = true
 86    gmail.inbox.emails(:unread, :before => Date.parse("2010-04-20"), :from => "myboss@gmail.com")
 87    
 88### 4) Work with emails!
 89
 90    # any news older than 4-20, mark as read and archive it...
 91    gmail.inbox.emails(:before => Date.parse("2010-04-20"), :from => "news@nbcnews.com").each do |email|
 92      email.mark(:read) # can also mark :unread or :spam
 93      email.archive!
 94    end
 95
 96    # delete emails from X...
 97    gmail.inbox.emails(:from => "x-fiancé@gmail.com").each do |email|
 98      email.delete!
 99    end
100
101    # Save all attachments in the "Faxes" label to a folder
102    folder = "/where/ever"
103    gmail.mailbox("Faxes").emails.each do |email|
104      if !email.message.attachments.empty?
105        email.message.save_attachments_to(folder)
106      end
107    end
108
109    # Save just the first attachment from the newest unread email (assuming pdf)
110    # For #save_to_file:
111    #   + provide a path - save to attachment filename in path
112    #   + provide a filename - save to file specified
113    #   + provide no arguments - save to attachment filename in current directory
114    email = gmail.inbox.emails(:unread).first
115    email.attachments[0].save_to_file("/path/to/location")
116
117    # Add a label to a message
118    email.label("Faxes")
119
120    # Or "move" the message to a label
121    email.move_to("Faxes")
122
123### 5) Create new emails!
124
125Creating emails now uses the amazing [Mail](http://rubygems.org/gems/mail) rubygem. See its [documentation here](http://github.com/mikel/mail). 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.
126
127    gmail.deliver do
128      to "email@example.com"
129      subject "Having fun in Puerto Rico!"
130      text_part do
131        body "Text of plaintext message."
132      end
133      html_part do
134        body "<p>Text of <em>html</em> message.</p>"
135      end
136      add_file "/path/to/some_image.jpg"
137    end
138    # Or, generate the message first and send it later
139    email = gmail.generate_message do
140      to "email@example.com"
141      subject "Having fun in Puerto Rico!"
142      body "Spent the day on the road..."
143    end
144    email.deliver!
145    # Or...
146    gmail.deliver(email)
147
148## Requirements
149
150* ruby
151* net/smtp
152* net/imap
153* tmail
154* shared-mime-info rubygem (for MIME-detection when attaching files)
155
156## Install
157
158    gem install ruby-gmail
159
160## License
161
162(The MIT License)
163
164Copyright (c) 2009 BehindLogic
165
166Permission is hereby granted, free of charge, to any person obtaining
167a copy of this software and associated documentation files (the
168'Software'), to deal in the Software without restriction, including
169without limitation the rights to use, copy, modify, merge, publish,
170distribute, sublicense, and/or sell copies of the Software, and to
171permit persons to whom the Software is furnished to do so, subject to
172the following conditions:
173
174The above copyright notice and this permission notice shall be
175included in all copies or substantial portions of the Software.
176
177THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
178EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
179MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
180IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
181CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
182TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
183SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.