Skip to content

Feat/update readme #96

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
EdOverride wants to merge 2 commits into
base: master
Choose a base branch
from
Open

Feat/update readme #96

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
8b1f033
Refactor readme
EdOverride Jun 27, 2019
4d988d1
Fix wrong path in readme example
EdOverride Jun 27, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
226 changes: 131 additions & 95 deletions README.markdown
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -42,109 +42,144 @@ A Rubyesque interface to Gmail, with all the tools you'll need. Search, read and
## Example Code:

### 1) Require gmail

require 'gmail'
```ruby
require 'gmail'
```

### 2) Start an authenticated gmail session

# 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.
gmail = Gmail.new(username, password)
# ...do things...
gmail.logout

Gmail.new(username, password) do |gmail|
# ...do things...
end
```ruby
# 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.
gmail = Gmail.new(username, password)
# ...do things...
gmail.logout
```

```ruby
Gmail.new(username, password) do |gmail|
# ...do things...
end
```

### 3) Count and gather emails!

# Get counts for messages in the inbox
gmail.inbox.count
gmail.inbox.count(:unread)
gmail.inbox.count(:read)

# Count with some criteria
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
gmail.inbox.count(:unread, :from => "myboss@gmail.com")

# Labels work the same way as inbox
gmail.mailbox('Urgent').count

# Getting messages works the same way as counting: optional flag, and optional arguments
# Remember that every message in a conversation/thread will come as a separate message.
gmail.inbox.emails(:unread, :before => Date.parse("2010-04-20"), :from => "myboss@gmail.com")

# Search the same way you do on Gmail's web interface:
gmail.inbox.emails(gm: 'before:2010-02-20 after:2010-03-20')
gmail.inbox.emails(gm: 'on:2010-04-15')
gmail.inbox.emails(gm: 'from:myfriend@gmail.com')
gmail.inbox.emails(gm: 'to:myfriend@gmail.com')
gmail.inbox.emails(gm: 'is:read from:myboss@gmail.com "you are a great employee"')

# Get messages without marking them as read on the server.
gmail.peek = true
gmail.inbox.emails(:unread, :before => Date.parse("2010-04-20"), :from => "myboss@gmail.com")

### 4) Work with emails!
```ruby
# Get counts for messages in the inbox
gmail.inbox.count
gmail.inbox.count(:unread)
gmail.inbox.count(:read)
```

```ruby
# Count with some criteria
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')
```

```ruby
# Combine flags and options
gmail.inbox.count(:unread, from: 'myboss@gmail.com')
```

```ruby
# Labels work the same way as inbox
gmail.mailbox('Urgent').count
```

```ruby
# Getting messages works the same way as counting: optional flag, and optional arguments
# Remember that every message in a conversation/thread will come as a separate message.
gmail.inbox.emails(:unread, before: Date.parse('2010-04-20'), from: 'myboss@gmail.com')
```

```ruby
# Search the same way you do on Gmail's web interface:
gmail.inbox.emails(gm: 'before:2010-02-20 after:2010-03-20')
gmail.inbox.emails(gm: 'on:2010-04-15')
gmail.inbox.emails(gm: 'from:myfriend@gmail.com')
gmail.inbox.emails(gm: 'to:myfriend@gmail.com')
gmail.inbox.emails(gm: 'is:read from:myboss@gmail.com "you are a great employee"')
```

```ruby
# Get messages without marking them as read on the server.
gmail.peek = true
gmail.inbox.emails(:unread, before: Date.parse('2010-04-20'), from: 'myboss@gmail.com')
```

# any news older than 4-20, mark as read and archive it...
gmail.inbox.emails(:before => Date.parse("2010-04-20"), :from => "news@nbcnews.com").each do |email|
email.mark(:read) # can also mark :unread or :spam
email.archive!
end

# delete emails from X...
gmail.inbox.emails(:from => "x-fiancé@gmail.com").each do |email|
email.delete!
end

# Save all attachments in the "Faxes" label to a folder
folder = "/where/ever"
gmail.mailbox("Faxes").emails.each do |email|
email.attachments.each do |attachment|
file = File.new(folder + attachment.filename, "w+")
file << attachment.decoded
file.close
end
end

# Add a label to a message
email.label("Faxes")

# Or "move" the message to a label
email.move_to("Faxes")
### 4) Work with emails!
```ruby
# any news older than 4-20, mark as read and archive it...
gmail.inbox.emails(before: Date.parse('2010-04-20'), from: 'news@nbcnews.com').each do |email|
email.mark(:read) # can also mark :unread or :spam
email.archive!
end
```

```ruby
# delete emails from X...
gmail.inbox.emails(from: 'x-fiancé@gmail.com').each do |email|
email.delete!
end
```

```ruby
# Save all attachments in the "Faxes" label to a folder
folder = '/where/ever'

gmail.mailbox('Faxes').emails.each do |email|
email.attachments.each do |attachment|
file = File.new(File.join(folder, attachment.filename), 'w+')
file << attachment.decoded
file.close
end
end
```

```ruby
# Add a label to a message
email.label('Faxes')
```

```ruby
# Or "move" the message to a label
email.move_to('Faxes')
```

### 5) Create new emails!

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.

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, generate the message first and send it later
email = gmail.generate_message 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)
```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, generate the message first and send it later
email = gmail.generate_message 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)
```

## Requirements

Expand All @@ -155,8 +190,9 @@ Creating emails now uses the amazing [Mail](http://rubygems.org/gems/mail) rubyg
* shared-mime-info rubygem (for MIME-detection when attaching files)

## Install

gem install ruby-gmail
```
gem install ruby-gmail
```

## License

Expand Down