Nylas Docs

The Nylas Developer Hub

Welcome to the Nylas developer hub. You'll find comprehensive guides and documentation to help you start working with Nylas as quickly as possible, as well as support if you get stuck. Let's jump right in!

Developer Guide

Inbox Folders and Labels with Python

Learn how to create email folders and labels and organize inboxes with the Nylas Python SDK. Build your email integration in 15 minutes.

Python is one of the most popular programming languages in the world due to its extensive collection of libraries, easy-to-understand syntax, and practical abstraction capabilities. We love Python so much that we’ve used it to build the Nylas Communications Platform, which enables developers to quickly integrate email, calendar, and contacts into their app. The Nylas Email API connects to all major providers, including Gmail, Outlook, Office365, Exchange, Yahoo, and more, and our Python SDK makes it simple to read emails directly from user email accounts.

This guide explains how to use the Nylas Python SDK and Email API to modify labels and folders and organize and inbox content with them. It covers the following steps:

  1. Set up your Nylas developer account and get your API keys
  2. Install the Nylas Python SDK
  3. View all labels for a Gmail account
  4. Create a label and apply it to a message
  5. Create a folder and move a message into it
  6. Explore the Nylas Email API

👍

Create Your Free Developer Account

Ready to build your email integration? Create your Nylas developer account to get started.

Set up Your Developer Account

After signing up for your Nylas developer account, follow our guide to get your API keys and authorize your first email account. When you complete this guide, you will have three tokens that you need to run the code examples below:

  • CLIENT_ID - The CLIENT ID found on the dashboard page for your Nylas App
  • `CLIENT_SECRET - The CLIENT SECRET found on the dashboard page for your Nylas App
  • ACCESS_TOKEN - The access token provided when you authenticate an account to your Nylas App

Install the Nylas Python SDK

Prerequisites

  • Ensure you have pip installed on your development environment.
  • Create a virtual environment to install Nylas.

Refer to the official Python documentation on pip and virtualenv to learn more about how to set this up.

Installing the SDK

With your virtual environment activated, run pip install nylas.

Congrats! You’re now ready to write code with the Nylas Python SDK.

Manage Folders and Labels

Configure the API Client

At its core, the Nylas Communication Platform is an API client that interfaces with all of the major email providers. First, import the APIClient class from the nylas package, and create a new instance of this class, passing the variables you gathered when you got your developer API keys. In the following example, replace CLIENT_ID, CLIENT_SECRET, and ACCESS_TOKEN with your values.

from nylas import APIClient

nylas = APIClient(
    CLIENT_ID,
    CLIENT_SECRET,
    ACCESS_TOKEN
)

🚧

Take care with your secrets

It’s not best practice to include secrets like this in your code. A more secure way to provide these values is to store them as environment variables and access them with the os.environ module.

View Labels and Folders For an Account

Depending on the account provider, there are two possible ways a user's email inbox can be organized: folders and labels. Gmail uses labels and all other providers, including Microsoft, Yahoo, and IMAP providers, use folders. Nylas makes it easy to detect the organization method an account uses by providing an organization_unit field on the account, which returns either folder or label. Take a look at the API reference for the Account endpoint to learn more about the values it returns.

The following code checks the value of organization_unit and returns the display_name and id for all folders or labels the account has.

if nylas.account.organization_unit == 'label': 
    labels = nylas.labels.all()

    print("This account has the following labels")
    for label in labels:
        print("Name: {} | ID: {}".format(label.display_name, label.id))

elif nylas.account.organization_unit == 'folder': 
    folders = nylas.folders.all()

    print("This account has the following folders")
    for folder in folders:
        print("Name: {} | ID: {}".format(folder.display_name, folder.id))

Create a Label or Folder

Now, it’s time to come up with a name for a new label and create it. In the following example, change the value of the string assigned to display_name to your preferred name. You must assign a value to display_name before saving the folder or label to Nylas and the third party provider with .save()

if nylas.account.organization_unit == 'label': 

    label = nylas.labels.create()
    label.display_name = "My Label"
    label.save()

elif nylas.account.organization_unit == 'folder': 

    folder = nylas.folders.create()
    folder.display_name = 'My Folder'
    folder.save()

Organize Email Inbox With Labels and Folders

The last thing we'll do is get the most recent email in the user's inbox and apply the label or move it into the folder we created.

if nylas.account.organization_unit == 'label':
  
    message = nylas.messages.first()
    message.add_label(label.id)

elif nylas.account.organization_unit == 'folder': 

    thread = nylas.threads.first()
    thread.update_folder(folder.id)

This example uses nylas.messages.first() and nylas.threads.first() to return a message object that represents the most recent email. Check out our tutorial on reading an email inbox to learn more about working with the message and thread objects. The .add_label() and .update_folder functions take a label or folder id as an argument; in this case, it’s the id for the folder or label we created earlier. The last line pushes the changes to Nylas with .save(); Nylas then syncs those changes with the third party provider.

Here is the entire code sample for convenience.

from nylas import APIClient
nylas = APIClient(
    CLIENT_ID,
    CLIENT_SECRET,
    ACCESS_TOKEN
)

# The organization_unit attribute for the account object lets you know if the account uses folders or labels for organization
# Gmail uses labels, all other providers use folders
# Account object reference: https://docs.nylas.com/reference#account
if nylas.account.organization_unit == 'label': # Gmail uses labels

    # Labels reference: https://docs.nylas.com/reference#labels
    labels = nylas.labels.all()

    # Gmail includes a number of default labels,
    # including Inbox, Important, Trash, Spam, and more
    print("This account has the following labels")
    for label in labels:
        print("Name: {} | ID: {}".format(label.display_name, label.id))

    # New labels must be assigned a display_name before they can be saved
    label = nylas.labels.create()
    label.display_name = "My Label"
    label.save()

    # Now we'll assign this label to the most recent message in the account's inbox
    message = nylas.messages.first()
    message.add_label(label.id)
    # Messages can have multiple labels
    # You can pass a list of id strings to .update_labels() to batch update.
    # Remove the label with message.remove_label(my_label_id)

elif nylas.account.organization_unit == 'folder': # All other providers use folders

    # Folders reference: https://docs.nylas.com/reference#folders
    folders = nylas.folders.all()

    # Microsoft accounts include a number of default folders,
    # including Inbox, Important, Trash, Spam, and more
    print("This account has the following folders")
    for folder in folders:
        print("Name: {} | ID: {}".format(folder.display_name, folder.id))

    # New folders must be assigned a display_name before they can be saved
    folder = nylas.folders.create()
    folder.display_name = 'My Folder'
    folder.save()

    # Now we'll move the most recent email thread to our new folder
    thread = nylas.threads.first()
    thread.update_folder(folder.id)
    # Note: an email message can only be contained in a single folder, but
    # a thread with multiple messages can span multiple folders
Ready to Build Your Email Integration?

Explore the Nylas Email API

If you’ve made it this far, congrats, you’ve used the Nylas Email API to create a Gmail label and apply it to an email message! 🎉There is plenty more that you can do with it: take a look at the following resources to learn more about the Nylas Communications Platform capabilities.

Updated 6 months ago

Inbox Folders and Labels with Python


Learn how to create email folders and labels and organize inboxes with the Nylas Python SDK. Build your email integration in 15 minutes.

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.