Only show these results:

Read an Inbox with Python

Learn how to read emails from Gmail, Outlook, and Exchange with the Nylas Python SDK. Build your email integration in 15 minutes.

Python Email Read

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 read emails. It covers the following steps:

  1. Set up your Nylas developer account and get your API keys
  2. Install the Nylas Python SDK
  3. Read data from an email inbox
  4. Explore the Nylas Email API

Prerequisites

Before you can start using the Nylas Python SDK, make sure you have done the following:

  • Sign up for your developer account.

  • Get your Nylas keys:

    • 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.

  • 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.

Read Data From an Email Inbox

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 with the os.environ module.

Messages vs Threads

Before reading content from your email inbox, it’s important to understand the difference between 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.

Reading Messages

Now, let’s take a look at messages.

message = nylas.messages.where(in_='inbox').first()
print("Subject: {} | ID: {} | Unread: {}".format(
    message.subject, message.id, message.unread))

This code uses the .first() function to return the most recent message in the account’s inbox.

It then returns the message subject, id, and unread status. You can also return the email body, snippet, recipient email addresses, folders, and labels. Take a look at the API reference for a list of everything you can access from a message object.

Reading Threads

Next, let’s get the 5 most recent unread threads from our email inbox and print their subject lines.

for thread in nylas.threads.where(unread=True, limit=5):
    print(thread.subject)

Each thread this code iterates through contains a list of message objects (more on that later). The .where() function allows you to filter and paginate the results based on a handful of criteria. By default, it returns the 100 most recent threads. In this case, we are only returning threads that are unread, and are limiting the results to the 5 most recent threads.

In addition to the subject line, thread.subject, you can also return lists of email addresses from the to, from, cc, and bcc fields, as well as unread and starred status. To learn more about pagination, filtering, and the parameters that are available to you, take a look at the API reference for threads.

Searching Messages and Threads

The search sub-endpoint is used to run a full-text search, that is proxied to the account's provider. Results are matched with objects that have been synced, and then returned. Search functionality is available for messages and threads, and the following example demonstrates how to search for messages that are from a specific email address.

message = nylas.messages.search("from:[email protected]")
print(message.subject)

Here are all of the code examples combined into a single block for easy copy and paste.

from nylas import APIClient

nylas = APIClient(
    CLIENT_ID,
    CLIENT_SECRET,
    ACCESS_TOKEN,
)

# Get the most recent message from the account's inbox
message = nylas.messages.where(from_='[email protected]', in_='inbox').first()
print("Subject: {} | ID: {} | Unread: {}".format(
message.subject, message.id, message.unread))

# List the 5 most recent unread threads
for thread in nylas.threads.where(from_='[email protected]', unread=True, limit=5):
    # Print the thread's subject
    print(thread.subject)
    
# Search for the most recent email from a specific address
# Also works for thread objects
message = nylas.messages.search("from:[email protected]")
print(message.subject)

Explore the Nylas Email API

If you’ve made it this far, congrats, you’ve successfully read an email inbox with the Nylas Email API! 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.