Manage inbox labels and folders with the Nylas Node.js SDK
The Nylas Node.js SDK and the Email API help you manage the following:
- Email labels for Gmail accounts
- Inbox folders for various providers, such as Microsoft Outlook, Exchange, and Office365
What you'll learn
In this tutorial, you'll learn how to do the following:
- View all labels and folders for an email account.
- Create a Gmail label and apply it to an email.
- Create an inbox folder to organize emails.
Prerequisites
Prerequisites include installing the Nylas Node.js SDK and setting up your environment. Before you start this tutorial, make sure that you do the following:
- Complete the Getting started with the Nylas Node.js SDK tutorial.
- Authenticate users with the Nylas Node.js SDK.
Step 1: Initialize the Nylas object
At its core, the Nylas Communication Platform is an API client that interfaces with all of the major email providers.
The Nylas
object provides access to every resource in Nylas APIs. Before making any request, you must initialize the Nylas
object with your client ID, client secret, and access token.
-
Call the
config
function and pass your client ID (<CLIENT_ID>
) and client secret (<CLIENT_SECRET>
). -
Call the
with
function and pass your access token (<ACCESS_TOKEN>
).
const Nylas = require('nylas');
Nylas.config({
clientId: <CLIENT_ID>,
clientSecret: <CLIENT_SECRET>
});
const nylas = Nylas.with(<ACCESS_TOKEN>);
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.
To change the base URL to the EU (Ireland) region, set apiServer: regionConfig[Region.Ireland].nylasAPIUrl
. The base API URL defaults to the US region.
const Nylas = require('nylas');
Nylas.config({
clientId: <CLIENT_ID>,
clientSecret: <CLIENT_SECRET>,
apiServer: regionConfig[Region.Ireland].nylasAPIUrl
});
const nylas = Nylas.with(<ACCESS_TOKEN>);
Step 3: View labels and folders for an email account
Gmail uses labels to organize email inboxes, while most other email providers use folders. Nylas detects the organization method by using the organizationUnit
, which returns either label
or folder
.
View labels
-
Add
if (account.organizationUnit == 'label')
to see if the account uses labels.Learn more about Accounts.
-
Call the
nylas.labels.list({})
function to return all the labels.The
nylas.labels.list({})
function returns default labels, such as Inbox, Important, Trash, and Spam, and any custom labels that the user created. Learn more about Labels. -
Optionally, specify attributes for the label object.
The following example logs the displayName
and id
for all labels that a Gmail account contains.
nylas.account.get().then(account =>{
if (account.organizationUnit == 'label') {
nylas.labels.list({}).then(labels => {
console.log("This account contains the following labels:")
for (const label of labels) {
console.log(`Name: ${label.displayName} | ID: ${label.id}`);
}
});
}
});
View folders
-
Check the
account
endpoint and addif (account.organizationUnit == 'folder')
to see if the account uses folders.Learn more about Accounts.
-
Call the
nylas.folders.list({})
function to return all the folders.Learn more about Folders.
-
Optionally, specify attributes for the folder object.
The following example logs the displayName
and id
for all folders that an email account contains.
nylas.account.get().then(account =>{
if (account.organizationUnit == 'folder') {
nylas.folders.list({}).then(folders => {
console.log("This account contains the following folders:")
for (const folder of folders) {
console.log(`Name: ${folder.displayName} | ID: ${folder.id}`);
}
});
}
});
Example: View labels and folders for an email account
const Nylas = require('nylas');
Nylas.config({
clientId: CLIENT_ID,
clientSecret: CLIENT_SECRET,
});
const nylas = Nylas.with(ACCESS_TOKEN);
nylas.account.get().then(account =>{
if (account.organizationUnit == 'label') {
nylas.labels.list({}).then(labels => {
console.log("This account contains the following labels:")
for (const label of labels) {
console.log(`Name: ${label.displayName} | ID: ${label.id}`);
}
});
}
if (account.organizationUnit == 'folder') {
nylas.folders.list({}).then(folders => {
console.log("This account contains the following folders:")
for (const folder of folders) {
console.log(`Name: ${folder.displayName} | ID: ${folder.id}`);
}
});
}
});
Step 4: Create labels and folders
You can create a Gmail label and apply it to emails or create a folder to organize emails.
Create a new label and apply it to an email
Create a Gmail label and apply it to the most recent email.
-
Define the new label name (
labelName
) andlabelToUpdate
.const labelName = 'Cat Pics!';
let labelToUpdate; -
Check the
account
endpoint and addif (account.organizationUnit == 'label')
to see if the account uses labels.nylas.account.get().then(account => {
if (account.organizationUnit == 'label') {
nylas.labels.forEach({}, checkLabel, createAndApplyLabel);
}
}); -
Call the
checkLabel (label)
function to check if the label already exists.function checkLabel (label) {
if (label.displayName == labelName) {
labelToUpdate = label;
};
} -
Call the
createAndApplyLabel ()
function to create the new label.The
.save()
function saves the changes to Gmail. Learn more about Labels.function createAndApplyLabel () {
if ( !labelToUpdate ) {
console.log(`Creating New Label: ${labelName}`)
labelToUpdate = new Label(nylas, {displayName: labelName});
labelToUpdate.save().then(label => {
addLabelToMostRecentMessage(label);
});
} else {
console.log(`${labelName} already exists!`)
addLabelToMostRecentMessage(labelToUpdate);
}
} -
Call the
addLabelToMostRecentMessage()
function to apply the new label to the most recent email.- The
nylas.messages.first()
function retrieves the most recent email from the inbox. - The
.push(label)
function applies the new label to the most recent email. - The
.save()
function saves the changes to Gmail. It logs the subject line and all labels that have been applied to the message.
Learn more about Messages.
function addLabelToMostRecentMessage (label) {
nylas.messages.first().then(msg => {
msg.labels.push(label);
console.log(`${label.displayName} applied to the most recent email.`)
msg.save().then(savedMsg => {
console.log(`Subject: ${savedMsg.subject}`);
console.log("This email contains the following labels")
console.log(savedMsg.labels);
})
})
} - The
Example: Create a Gmail label and apply it to an email
const Nylas = require('nylas');
const { Label } = require('nylas/lib/models/folder');
Nylas.config({
clientId: CLIENT_ID,
clientSecret: CLIENT_SECRET,
});
const nylas = Nylas.with(ACCESS_TOKEN);
// Assign a string to use for the display name of the new label
const labelName = 'Cat Pics!';
let labelToUpdate;
nylas.account.get().then(account => {
// account.organizationUnit will return 'label' or 'folder' depending on provider capabilities
if (account.organizationUnit == 'label') {
nylas.labels.forEach({}, checkLabel, createAndApplyLabel);
}
});
function checkLabel (label) {
if (label.displayName == labelName) {
labelToUpdate = label;
};
}
function createAndApplyLabel () {
// Make sure that we aren't duplicating an existing label name
if ( !labelToUpdate ) {
// If the label doesn't exist, create it and pass it to the function that assigns it to the most recent email
console.log(`Creating New Label: ${labelName}`)
labelToUpdate = new Label(nylas, {displayName: labelName});
labelToUpdate.save().then(label => {
addLabelToMostRecentMessage(label);
});
} else {
// If the label already exists, pass it to the function that assigns it to the most recent email
console.log(`${labelName} already exists!`)
addLabelToMostRecentMessage(labelToUpdate);
}
}
function addLabelToMostRecentMessage (label) {
nylas.messages.first().then(msg => {
console.log(`${label.displayName} applied to the most recent email.`)
// Add the label to the most recent email and save it
msg.labels.push(label);
msg.save().then(savedMsg => {
console.log(`Subject: ${savedMsg.subject}`);
//Gmail includes default labels, including Inbox, Important, Trash, Spam, and more
console.log("This email contains the following labels")
console.log(savedMsg.labels);
})
})
}
Create a folder to organize emails
Most email providers, including Microsoft Outlook, Exchange, Office365, and Yahoo, use folders to organize emails. In this tutorial, you'll create a folder and add the most recent email to the folder.
The syntax is mostly the same as creating a label. However, an email message can only exist within one folder, while an email thread can be associated with several folders. Learn more about Threads.
-
Define the new folder name (
folderName
) andfolderToUpdate
.const folderName = 'Cat Pics!';
let folderToUpdate; -
Check the
account
endpoint and addif (account.organizationUnit == 'folder')
to see if the account uses folders.nylas.account.get().then(account => {
if (account.organizationUnit == 'folder') {
nylas.folders.forEach({}, checkfolder, createAndApplyfolder);
}
}); -
Call the
checkFolder (folder)
function to check if the folder already exists.function checkFolder (folder) {
if (folder.displayName == folderName) {
folderToUpdate = folder;
};
} -
Call the
createAndApplyFolder ()
function to create the new folder.The
.save()
function saves the changes to the user's inbox. Learn more about Folders.function createAndApplyFolder () {
if ( !folderToUpdate ) {
console.log(`Creating New folder: ${folderName}`)
folderToUpdate = new Folder(nylas, {displayName: folderName});
folderToUpdate.save().then(folder => {
addMostRecentMessageToFolder(folder);
});
} else {
console.log(`${folderName} already exists!`)
addMostRecentMessageToFolder(folderToUpdate);
}
} -
Call the
addMostRecentMessageToFolder()
function to add the most recent email to the folder.- The
nylas.messages.first()
function retrieves the most recent email from the inbox and assignsmsg.folder
to the folder that you created. The most recent email is moved to the folder. - The
.save()
function saves the changes to the user's inbox. It logs the subject line and the folder.
Learn more about Messages.
- The
Example: Create a folder to organize emails
const Nylas = require('nylas');
const { default: Folder } = require('nylas/lib/models/folder');
Nylas.config({
clientId: CLIENT_ID,
clientSecret: CLIENT_SECRET,
});
const nylas = Nylas.with(ACCESS_TOKEN);
// Assign a string to use for the display name of the new folder
const folderName = 'Cat Pics!';
let folderToUpdate;
nylas.account.get().then(account => {
// account.organizationUnit will return 'label' or 'folder' depending on provider capabilities
if (account.organizationUnit == 'folder') {
nylas.folders.forEach({}, checkfolder, createAndApplyFolder);
}
});
function checkfolder (folder) {
if (folder.displayName == folderName) {
folderToUpdate = folder;
};
}
function createAndApplyFolder () {
// Make sure that we aren't duplicating an existing folder name
if ( !folderToUpdate ) {
// If the folder doesn't exist, create it and pass it to the function that moves it to the most recent email
console.log(`Creating New folder: ${folderName}`)
folderToUpdate = new Folder(nylas, {displayName: folderName});
folderToUpdate.save().then(folder => {
addMostRecentMessageToFolder(folder);
});
} else {
// If the folder already exists, pass it to the function that assigns it to the most recent email
console.log(`${folderName} already exists!`)
addMostRecentMessageToFolder(folderToUpdate);
}
}
function addMostRecentMessageToFolder (folder) {
nylas.messages.first().then(msg => {
console.log(`${folder.displayName} applied to the most recent email.`)
// Add the folder to the most recent email and save it
msg.folder = folder;
msg.save().then(savedMsg => {
console.log(`Subject: ${savedMsg.subject}`);
// Email providers have default folders including Inbox, Drafts, Trash, Sent Items, and more
console.log("This email contains the following folders")
console.log(savedMsg.folder);
})
})
}
More resources
If you’ve made it this far, congrats! You’ve successfully learned how to manage inbox folders and labels with the Nylas Email API! There's plenty more that you can do with Nylas. Take a look at the following resources:
- Follow our Node.js SDK tutorials.
- Learn more about the Nylas API.
- Learn more about the Nylas Email API.
- Read about how the Nylas Communications Platform works.