Read email messages and threads with Ruby

This page explains how to use the Nylas Ruby SDK and Email API to search for and read email messages and threads from an end user's inbox.

Messages versus Threads

Messages are the fundamental object of the Nylas platform and the core building block for most email applications. Messages contain several pieces of information, such as when the message was sent, the sender's address, to whom it was sent, and the message body. They can also contain files (attachments), calendar event invitations, and more.

Threads are first-class objects that represent collections of messages which are related to each other, and result from people replying to an email conversation. For Gmail and Microsoft Exchange accounts, Nylas threads messages together so that they are as similar as possible to their representation in those environments. For all other providers, including generic IMAP, Nylas threads messages using a custom JWZ-inspired algorithm.

For more information, see the Messages and Threads reference documentation.

Before you begin

Before you start, you must have done the following tasks:

Installed and set up the Nylas Ruby SDK.
Authenticated one or more end users.

Read email messages from an inbox

To read email messages from an end user's inbox, create a Message object and pass a query to it. This returns a list containing only the most recent email message in the end user's inbox.

query_params = { in: "inbox", limit: 1 }
messages, _ = nylas.messages.list(identifier: "<NYLAS_GRANT_ID>",  query_params: query_params)

messages.each {|message|
  puts "Subject: #{message[:subject]} | ID: #{message[:id]} | " \
      "Unread: #{message[:unread]}"
}

You can also return the body content of the email message, its snippet, its recipients' email addresses, and any associated folders or labels. For more information, see the Messages reference documentation.

Read threads from an inbox

To read threads from an end user's inbox, create a Threads object and pass a query to it. This returns a list containing only the five most recent unread threads in an end user's inbox.

query_params = { in: "inbox", limit: 5 }
threads, _ = nylas.threads.list(identifier: "<NYLAS_GRANT_ID>",  query_params: query_params)

threads.each {|threads|
  puts "Subject: #{threads[:subject]} | ID: #{threads[:id]} | " \
      "Unread: #{threads[:unread]}"
}

You can also retrieve the senders' email addresses, the recipients' email addresses, the email addresses in the CC and BCC fields, and the unread and starred parameters. See the Threads reference documentation for more information.

Search an end user's inbox

When Nylas runs a search on an end user's inbox, that search is proxied to the account's provider. Nylas matches results with synced objects, and returns them. You can search for both email messages and threads.

The example below shows how to search for and read email messages and threads from an end user's inbox.

require 'nylas'

nylas = Nylas::Client.new(
    api_key: "<NYLAS_API_KEY>"
)

# Get the most recent email message from the account's inbox.
query_params = { in: "inbox", limit: 1 }
messages, _ = nylas.messages.list(identifier: "<NYLAS_GRANT_ID>",  
    query_params: query_params)

messages.each {|message|
  puts "Subject: #{message[:subject]} | ID: #{message[:id]} | " \
      "Unread: #{message[:unread]}"
}

# List the 5 most recent unread threads
query_params = { in: "inbox", limit: 5 }

threads, _ = nylas.threads.list(identifier: "<NYLAS_GRANT_ID>",  
    query_params: query_params)

threads.each {|threads|
  puts "Subject: #{threads[:subject]} | ID: #{threads[:id]} | " \
      "Unread: #{threads[:unread]}"
}

# Search for the most recent email message or thread from a specific address.
query_params = {
  search_query_native: "from:swag@example.com"
}

messages, _ = nylas.messages.list(identifier: "<NYLAS_GRANT_ID>", query_params: query_params)

messages.each {|message|
  puts "message[:subject]}"
}

Explore the Email API

If you've made it to this point, congratulations! You've learned how to search for and read email messages and threads with the Nylas Ruby SDK and Email API! 🎉

There's plenty more that you can do with Nylas. Take a look at the following resources to learn more: