Gmail for Ruby

A Ruby interface to Gmail API: Search, read and send multipart emails, archive, mark as read/unread, delete emails, and manage labels. Everything goes through Gmail API (and not through IMAP or SMTP protocols)

Gem Version Build Status Dependency Status

Notice

If for your usecase, the gem is too limited there are two solutions for you:

  1. Contribute ;)
  2. Look at Gmail Api doc to:
    • Do custom query by adding parameters I didn’t talk about in my doc
    • If for some reason I forgot to build some methods, note that you can call fully custom request via Gmail.client (Standard Google Api Client)

To Do

  • write proper error handling

Installation

gem install gmail-api-ruby

Initialization

“by Gmail.client_id = “…Your app client id…” or the email from your service account credentials Gmail.client_secret = “…Your app Secret…” or the pem version of hte api key for service account Gmail.refresh_token = “…the refresh token of the Gmail account you want to use…” or the account email address for service account auth # Or for service Accounts Gmail.auth_method = “service_account” Gmail.client_id = “… or the email from your service account credentials…” Gmail.client_secret = “…pem version of the api key …” Gmail.email_account = “…the email account you’re going to use” Gmail.auth_scopes = [http://mail.google.com] # an array of the permissions required.

“

Usage

“by require “gmail”

“

Common methods

this works for Messages, Labels, Drafts and Threads (everything)

“by Gmail::Message.all Gmail::Message.all(maxResults: -1) #will parse everything. Use with care. Can through request timeout if used in web apps Gmail::Message.get(message_id) some_gmail_message.delete

“

this will work for Messages and Threads

“by some_message.archive some_message.unarchive some_message.trash some_message.untrash some_message.star some_message.unstar some_message.mark_as_read some_message.mark_as_unread

Gmail::Message.search(in: “labelId” from: “[email protected]”, to: “[email protected], [email protected]”, subject: “some subject”, after: “date”, before: “date”, has_words: “some words”, has_not_words: “some text”) Gmail::Message.search(“some words”) #search as you would do in gmail interface

“

Message

Create a Message object

“by m = Gmail::Message.new( from: “[email protected]”, to: “[email protected]”, subject: “this is the subject”, body: “this is a text body”)

“

If you want a multipart message

“by m = Gmail::Message.new( from: “[email protected]”, to: “[email protected]”, subject: “this is the subject”, text: “this is a text body”, html: “

this is a html body

”, labelIds: [cool label, Newsletter] #labelIds is always array of labels )

“

From this you can create a Draft in Gmail

“by m.create_draft

“

or send the Message

“by m.deliver

“

or simply insert the message in the user mailbox

“by m.insert

“

Notice that the Message object can use from, to, cc, bcc, threadId, labelIds, text, html, body

If you need to send Message or create draft with custom headers or set other headers. Or if you need to create a different multipart email, you need to build the “raw” email yourself

example:

“by mail = Mail.new #this is the native ruby Mail object # # construct your Mail object # raw = Base64.urlsafe_encode64 mail.to_s m = Gmail::Message.new(raw: raw)

“

In that scenario, you still assign, if needed, ThreadId and labelIds as previously

“by m.threadId = “somethreadId” m.labelIds = [cool label]

“

If you want to quickly generate a reply or a forward to message

“by # this will construct everything for you, keeping the subject the thread etc as it would happen in Gmail # reply only to the sender of Message m. msg = m.reply_sender_with Gmail::Message.new(body: “some reply text”) # reply to all (sender, to (without yourself) and cc) msg = m.reply_all_with Gmail::Message.new(body: “some reply text”) # forward msg = m.forward_with Gmail::Message.new(body: “some forward text”, to: “[email protected]”) # Note that the above will not send the resulting msg msg.deliver #to send the constructed reply message

“

Other stuffs that you can do with Message object

“by m.detailed #if for any reason Google did send us the full detail of on email object m.thread #to get the associated Thread m.inbox? #to know if email is in inbox m.sent? #to know if email is a sent email m.unread? #to know if email is unread

“

Those are basics helpers feel free to add more if you want (ex: starred?, important?, etc)

Thread

Get a thread

“by one_thread = Gmail::Thread.get(thread_id)

“

or

“by one_thread = one_message.thread

“

Filter messages in Thread

“by one_thread.unread_messages one_thread.sent_messages

“

Expand messages in Thread

“by one_thread.detailed #this will return a thread object but with all messages detailed one_thread.messages #this will return an array of message objects

“

Draft

As we explained in Message, you create a draft with

“by d = some_message.create_draft

“

Modify it with

“by d.message.subject = “some different subject than before” d.save

“

send it with

“by d.deliver

“

Label

You can create a label like this:

“by l = Gmail::Label.new l.name = “different Name” l.messageListVisibility = “hide” #can be ‘hide’ or ‘show’ l.labelListVisibility = “labelShowIfUnread” #can be “labelShowIfUnread”, “labelShow”, “labelHide” l.save

“

You can modify a label like this:

“by l = Gmail::Label.get(“labelId”) l.name = “different Name” l.messageListVisibility = “hide” l.labelListVisibility = “labelShowIfUnread” l.save

“

You can use Labels to directly access box information

“by l.detailed #will display number of messages and number of threads if you don’t see it

“

For system labels like inbox, sent, trash, important, starred, draft, spam, unread, category_updates, category_promotions, category_social, category_personal, category_forums

“by l = Gmail::Label.inbox

“

Access threads and messages from labels

“by l.threads l.messages

l.unread_threads
l.unread_messages

“

Access threads, drafts and messages with labels

“by Gmail::Message.all(labelIds: [UNREAD, INBOX])

“

License

Copyrignt (c) 2015 Julien Hobeika

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.