Only show these results:

Read messages and threads with the Nylas Node.js SDK

The Nylas Node.js SDK is the quickest way to integrate email account data into your app with JavaScript and the Nylas Email API. The Email API connects to all major providers, including Gmail, Outlook, Office365, Exchange, Yahoo, and more, and the Nylas Node.js 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 Node.js SDK and Email API.

What you'll learn

In this tutorial, you'll learn how to do the following tasks:

  • Read email messages in a user's inbox.
  • Read threads in a user's inbox.

Prerequisites

Before you start, install the Nylas Node.js SDK and set up your environment:

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 Nylas object

At its core, the Nylas platform is an API client that interfaces with all of the major email providers.

The Nylas object provides access to every resource in the Nylas API. Before you make any API requests, you must initialize the Nylas object with your client ID, client secret, and access token:

  1. Call the .config() function and pass your <CLIENT_ID> and <CLIENT_SECRET>.
  2. Call the .with() function and pass your <ACCESS_TOKEN>.

All together, your code should look like the example below.

const Nylas = require('nylas');
 
Nylas.config({
 clientId: <CLIENT_ID>,
 clientSecret: <CLIENT_SECRET>
});
 
const nylas = Nylas.with(<ACCESS_TOKEN>);

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.

If you're using the Node.js SDK v6.x and the Nylas API v3 Beta: The EU region is currently not available.

To change the API URL, pass the API_URL parameter to Nylas.config():

const Nylas = require('nylas');
 
Nylas.config({
 clientId: <CLIENT_ID>,
 clientSecret: <CLIENT_SECRET>,
 apiServer: regionConfig[Region.Ireland].nylasAPIUrl
});
 
const nylas = Nylas.with(<ACCESS_TOKEN>);

If you're using the Nylas EU region: The base API URL defaults to the US region, but you can specify apiServer: regionConfig[Region.Ireland].nylasAPIUrl 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 end user'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.

The following code snippet returns the most recent unread message in an email account's inbox, along with its subject and id.

nylas.messages.first({in: 'inbox'}).then(message =>{
    console.log(`Subject: ${message.subject} | ID: ${message.id} | Unread: ${message.unread}`);
});

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 .list() function to filter and paginate threads. By default, the .list() function returns the 100 most recent threads associated with the email account, but you can filter and paginate the results.

The following code snippet reads the five most recent unread threads from the email account's inbox and returns their subject parameter.

nylas.threads.list({unread: true, limit: 5}).then(threads =>{
    for (let thread of threads) {
        console.log(thread.subject);
    }
});

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.

Example: Read messages and threads from an inbox

The following example returns the most recent unread email message and the five most recent unread threads from an account's inbox.

const Nylas = require('nylas');

Nylas.config({
    clientId: CLIENT_ID,
    clientSecret: CLIENT_SECRET,
});
  
const nylas = Nylas.with(ACCESS_TOKEN);

// List the most recent unread message with its subject line.
nylas.messages.first({in: 'inbox'}).then(message =>{
    console.log(`Subject: ${message.subject} | ID: ${message.id} | Unread: ${message.unread}`);
});

// List the five most recent unread email threads with their subject lines.
nylas.threads.list({unread: true, limit: 5}).then(threads =>{
    for (let thread of threads) {
        console.log(thread.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 these resources: