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:
- Set up your Nylas developer account and get your API keys
- Install the Nylas Python SDK
- View all labels for a Gmail account
- Create a label and apply it to a message
- Create a folder and move a message into it
- Explore the Nylas Email API
Prerequisites
Before you can start using the Nylas Python SDK, make sure you have done the following:
Prerequisites
Before you can start using the Nylas Java SDK, make sure you have done the following:
- Sign up for your developer account.
- Get your developer keys. You need to have your:
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 Java SDK
The Nylas Java SDK requires Java 8 or above.
For the following examples, replace X.X.X
with the version you want to use. Take a look at the list of releases to learn about the versions that are available.
Setup with Gradle
If you're using Gradle, add the following to your dependencies section of build.gradle
:
implementation("com.nylas.sdk:nylas-java-sdk:X.X.X")
Setup with Maven
For projects using Maven, add the following to your POM file:
<dependency>
<groupId>com.nylas.sdk</groupId>
<artifactId>nylas-java-sdk</artifactId>
<version>X.X.X</version>
</dependency>
- Ensure you have pip installed on your development environment.
- Create a virtual environment to install Nylas.
Installing the Nylas Python SDK
With your virtual environment activated, run:
pip install nylas
Congratulations!
You’re now ready to write code with the Nylas Python SDK.
Manage Folders and Labels
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:/docs/api/v2/#tag--Accounts
if nylas.account.organization_unit == 'label': # Gmail uses labels
# Labels reference: /docs/api/v2/#tag--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: /docs/api/v2/#tag--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
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.
- Learn about some of the more important features of the Nylas Email API.
- Take a look at additional code examples for the Python SDK to see what else you can do with email, calendars, and contacts.
- Follow our tutorials to learn about other aspects of the Nylas Email, Calendar, and Contacts APIs.
- Read about how the Nylas Communications Platform works.
- Review The Basics to learn about what it takes to integrate the Nylas Email API into your app.