Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

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