Read inbox messages and threads with the Nylas Ruby SDK
The Nylas Ruby SDK is the quickest way to integrate email account data into your app with Ruby and the Nylas Email API. The Email API connects to all major providers, including Gmail, Outlook, Office365, Exchange, Yahoo, and more, and the Ruby SDK makes it easy to read data directly from user email accounts.
This page discusses how to read inbox messages and threads with the Nylas Ruby SDK and Email API.
What you'll learn
In this tutorial, you'll learn how to do the following tasks:
- Read messages in a user's inbox.
- Read threads in a user's inbox.
- Search messages and threads in a user's inbox.
Prerequisites
Before you start this tutorial, you must install the Nylas Ruby SDK and set up your environment. See Get started with the Nylas Ruby SDK for more information.
Messages and 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 a collection of messages. Messages are threaded together with a variety of heuristics. For Gmail and Microsoft Exchange accounts, messages are threaded together in a way that is as close as possible to the representation in their environments. For all other providers, including generic IMAP, messages are threaded using a custom JWZ-inspired algorithm.
Step 1: Initialize the API
object
All of the functionality of the Nylas platform is available through the API
object. Before you make requests, initialize the API
object with your client ID, client secret, and access token:
#!/usr/bin/env ruby
CLIENT_ID = 'your_nylas_client_id'
CLIENT_SECRET = 'your_nylas_client_secret'
ACCESS_TOKEN = 'your_account_access_token'
require 'nylas'
nylas = Nylas::API.new(
app_id: CLIENT_ID,
app_secret: CLIENT_SECRET,
access_token: ACCESS_TOKEN
)
For more information on initializing the API
object, see Get started with the Nylas Ruby SDK.
Step 2: (Optional) Change the base API URL
You can choose to change the base API URL depending on your location:
Location | API URL | Scheduler API URL |
---|---|---|
United States (Oregon) | https://api.nylas.com |
https://api.schedule.nylas.com |
Europe (Ireland) | https://ireland.api.nylas.com |
https://ireland.api.schedule.nylas.com |
For more information, see Data residency and Migration guide for data centers.
Pass the API_URL
parameter to change the base API URL:
#!/usr/bin/env ruby
CLIENT_ID = 'your_nylas_client_id'
CLIENT_SECRET = 'your_nylas_client_secret'
ACCESS_TOKEN = 'your_account_access_token'
API_URL='your_base_api_url'
require 'nylas'
nylas = Nylas::API.new(
app_id: CLIENT_ID,
app_secret: CLIENT_SECRET,
access_token: ACCESS_TOKEN,
api_server: API_URL
)
If you're using the Nylas EU region: The base API URL defaults to the US region, but you can specify api_server: 'https://ireland.api.nylas.com'
to use the EU region. See Data Residency for more information.
Step 3: Read messages and threads from an inbox
You can read both individual messages and threads from an email account's inbox. You can also use the Search sub-endpoint to search for specific messages and threads.
Read messages from an inbox
To read individual messages from a user's inbox, you must fetch one or more messages from their account. Use the .where()
function to filter messages, and the .limit()
function to return only a specific number of messages.
This example returns the most recent unread
message in an email account's inbox, along with its subject
and id
:
messages = nylas.messages.where(in:"inbox").limit(1)
messages.each{ |message|
date = Time.at(message.date)
puts(
"Subject: #{message.subject} | ID: #{message.id} | Unread: #{message.unread}"
)
}
Learn More
You can also return the email body, snippet, recipients' email addresses, associated folders, and associated labels. See the Messages documentation for more information.
Read threads from an inbox
You can also read threads from an email account's inbox. Each thread
object contains a list of message
objects that are part of the thread. Use the .where()
function to filter and paginate threads.
By default, the .where()
function returns the 100 most recent threads associated with the email account, but you can filter and paginate the results.
This example reads the five most recent unread
threads from the email account's inbox and returns their subject
parameter:
threads = nylas.threads.where(in:"inbox", unread: true).limit(5)
threads.each{ |thread|
puts(thread.message_ids[0])
}
In addition to the message ID (thread.message_ids[0]
), 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 documentation for more information.
Step 4: Search messages and threads in an inbox
You can use the Search sub-endpoint to run a full-text search that is proxied through the email account's provider:
message = nylas.messages.search('from:[email protected]')
messages.each{ |message|
puts(message.subject)
}
Nylas matches the results of the search with objects that it has synced and returns them.
Example: Search messages and threads in an inbox
#!/usr/bin/env ruby
CLIENT_ID = 'your_nylas_client_id'
CLIENT_SECRET = 'your_nylas_client_secret'
ACCESS_TOKEN = 'your_account_access_token'
require 'nylas'
nylas = Nylas::API.new(
app_id: CLIENT_ID,
app_secret: CLIENT_SECRET,
access_token: ACCESS_TOKEN
)
# Get the most recent message from the account's inbox
messages = nylas.messages.where(in:"inbox").limit(1)
messages.each{ |message|
date = Time.at(message.date)
puts(
"Subject: #{message.subject} | ID: #{message.id} | Unread: #{message.unread}"
)
}
# List the 5 most recent unread threads
threads = nylas.threads.where(in:"inbox", unread: true).limit(5)
threads.each{ |thread|
puts(thread.message_ids[0])
}
# Search for the most recent email from a specific address
# Also works for thread objects
message = nylas.messages.search('from:[email protected]')
messages.each{ |message|
puts(message.subject)
}
More resources
If you’ve made it this far, congrats! You’ve successfully learned how to read messages and threads from a user's inbox with the Nylas Email API! 🎉
There's plenty more that you can do with Nylas. Take a look at these resources:
- Follow our Ruby SDK tutorials.
- Learn more about the Nylas API.
- Learn more about the Nylas Email API.
- Read about how the Nylas platform works.
- Read our How to read email inbox data With the Nylas Ruby SDK blog post.