Read inbox messages and threads with the Nylas Ruby SDK
The Nylas Email API connects to all major providers, including Gmail, Outlook, Office365, Exchange, Yahoo, and more, and the Nylas Ruby SDK makes it easy to read data directly from user email accounts.
This guide explains how to use the Nylas Ruby SDK and Email API to read inbox messages and threads with Ruby.
What you'll learn
In this tutorial, you'll learn how to do the following:
- Read inbox messages.
- Read inbox threads.
- Search inbox messages and threads.
Prerequisites
Prerequisites include installing the Nylas Ruby SDK and setting up your environment. Before you start this tutorial, make sure that you complete the Getting started with the Nylas Ruby SDK tutorial.
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 a message was sent, the sender's address, to whom it was sent, and the message body. Message 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 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 Communications 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, refer to the Getting started with the Nylas Ruby SDK tutorial.
Step 2: Change the base API URL
You can optionally 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 API_URL
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
)
Step 3: Read Data From an Email Inbox
Learn how to read inbox messages and threads.
Read inbox messages
Use the .limit(1)
function to return the most recent message in the account’s inbox.
The following example returns the most recent unread
message 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}"
)
}
You can return the email body, snippet, recipient email addresses, folders, and labels. Learn more about Messages.
Read inbox threads
Each thread
iterates through a list of message objects in the thread. Call the .where()
function to filter and paginate threads.
By default, the .where()
function returns the 100 most recent threads, but you can filter and paginate the results. The examples below read the five most recent unread threads from the email inbox and with their subject.
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 following:
- From addresses
- To addresses
- CC and BCC fields
unread
andstarred
indicating whether the thread includes unread or starred messages
Learn more about Threads.
Search inbox messages and threads
You can use the search sub-endpoint to run a full-text search that is proxied through the account's provider. Nylas matches the results with objects that is has synced, and returns them.
message = nylas.messages.search('from:[email protected]')
messages.each{ |message|
puts(message.subject)
}
Example: Search inbox messages and threads
#!/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 inbox messages and threads with the Nylas Email API! There's plenty more that you can do with Nylas. Take a look at the following resources:
- Follow our Ruby SDK tutorials.
- Learn more about the Nylas API.
- Learn more about the Nylas Email API.
- Read about how the Nylas Communications Platform works.
- Read the blog post How to read email inbox data With the Nylas Ruby SDK.