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 a more friendly API, is well tested, better documented and has many other improvements.

Code Quality Rank: L4
Monthly Downloads: 200,455
Programming language: Ruby
License: GNU General Public License v3.0 or later
Tags: Third-party APIs    
Latest version: v0.7.1

gmail alternatives and similar gems

Based on the "Third-party APIs" category.
Alternatively, view gmail alternatives based on common mentions on social networks and blogs.

Do you think we are missing an alternative of gmail or a related project?

Add another 'Third-party APIs' Gem


Build Status Code Climate Gem Version Coverage Status

Deprecation Notice

As of version 0.7.0 (Aug 19, 2018) this gem is officially deprecated and will no longer be maintained. Please instead use Google's official Gmail API Ruby Client, which uses the Gmail API rather than IMAP and has significantly better performance and reliability.


This gem is a Rubyesque interface to Google's Gmail via IMAP. 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.

Reporting Issues

As of version 0.7.x, we are accepting pull requests for critical security patches only.

This gem uses the Mail gem for messages, attachments, etc. Unless your issue is related to Gmail integration specifically, please refer to RFC-5322 (email specification) and the Mail gem.


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.
  • Ruby 1.8.7 users should use gmail v0.4.1


  • 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.

require 'gmail'

Authenticating gmail sessions

This will let you automatically log in to your account.

gmail = Gmail.connect(username, password)
# play with your gmail...

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.connect(username, password) do |gmail|
  # play with your gmail...

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:

Gmail.connect!(username, password)
Gmail.connect!(username, password) {|gmail| ... play with gmail ... }

You can also check if you are logged in at any time:

Gmail.connect(username, password) do |gmail|

XOAuth authentication

From v0.4.0 it's possible to authenticate with your Gmail account using XOAuth method. It's very simple:

gmail = Gmail.connect(:xoauth, "[email protected]", 
  :token           => 'TOKEN',
  :secret          => 'TOKEN_SECRET',
  :consumer_key    => 'CONSUMER_KEY',
  :consumer_secret => 'CONSUMER_SECRET'
gmail = Gmail.connect(:xoauth2, '[email protected]', 'ACCESS_TOKEN')

For more information check out the gmail_xoauth gem from Nicolas Fouché.

XOAuth2 authentication

You can use the oauth2 token to connect to Gmail. The connect method takes 3 paramaters.

gmail = Gmail.connect(:xoauth2, "[email protected]", "TOKEN")

You can use omniauth-google-oauth2 to fetch the token. Once the omniauth authorization has been completed, you'll be left with a auth.credentials.token you can pass in as the third paramater to Gmail.connect.

Counting and gathering emails

Get counts for messages in the inbox:


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 => "[email protected]")
gmail.inbox.count(:to => "[email protected]")

Combine flags and options:

gmail.inbox.count(:unread, :from => "[email protected]")

Browsing labeled emails is similar to work with inbox.


Getting messages works the same way as counting: 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 => "[email protected]")

The gm option enables use of the Gmail search syntax.

gmail.inbox.emails(gm: '"testing"')

You can also use one of aliases:


Also you can manipulate each message using block style:

gmail.inbox.find(:unread).each do |email|

Note: The :before and :after filters only go as far as to search for messages on the date:

# E.g. the following will return messages between 2016-01-01 00:00:00 and 2016-04-05 00:00:00
    :after => Time.parse('2016-01-01 07:50:21'),
    :before => Time.parse('2016-04-05 21:55:05')

Working with emails!

Any news older than 4-20, mark as read and archive it:

gmail.inbox.find(:before => Date.parse("2010-04-20"), :from => "[email protected]").each do |email|
  email.read! # can also unread!, spam! or star!

Delete emails from X:

gmail.inbox.find(:from => "[email protected]").each do |email|

Save all attachments from the "Faxes" label to a local folder (uses functionality from Mail gem):

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)

You can also use #label method instead of #mailbox:

gmail.label("Faxes").emails.each {|email| ... }

Save just the first attachment from the newest unread email (assuming pdf):

email = gmail.inbox.find(:unread).first
attachment = email.attachments[0]
File.write(File.join(folder_path, attachment.filename), attachment.body.decoded)

Add a label to a message:


Example above will raise error when you don't have the Faxes label. You can avoid this using:

email.label!("Faxes") # The `Faxes` label will be automatically created now

You can also move message to a label/mailbox:


There are also few shortcuts to mark messages quickly:


Managing labels

With Gmail gem you can also manage your labels. You can get list of defined labels:


Create new label:


Remove labels:


Or check if given label exists:

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

gmail.labels.localize(:all) # => "[Gmail]\All Mail"
                            # => "[Google Mail]\All Mail"

Composing and sending emails

Creating emails now uses the amazing Mail rubygem. See its documentation here. 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.

gmail.deliver do
  to "[email protected]"
  subject "Having fun in Puerto Rico!"
  text_part do
    body "Text of plaintext message."
  html_part do
    content_type 'text/html; charset=UTF-8'
    body "<p>Text of <em>html</em> message.</p>"
  add_file "/path/to/some_image.jpg"

Or, compose the message first and send it later

email = gmail.compose do
  to "[email protected]"
  subject "Having fun in Puerto Rico!"
  body "Spent the day on the road..."
email.deliver! # or: gmail.deliver(email)


If you are having trouble connecting to Gmail:


Core Team

This project follows on Open Governance model. The Core Team is responsible for technical guidance, reviewing/merging PRs, and releases.

Legacy Contributors


  • Copyright (c) 2015-2018 GmailGem team
  • Copyright (c) 2010-2014 Kriss 'nu7hatch' Kowalik
  • Copyright (c) 2009-2010 BehindLogic

Licensed under the MIT license. See LICENSE for details.

*Note that all licence references and agreements mentioned in the gmail README section above are relevant to that project's source code only.