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

Python SDK

The Nylas Python SDK Quickstart Guide

The Nylas Communications Platform allows developers to quickly build features that connect to every inbox, calendar, and contacts book in the world. The Nylas SDKs are the quickest way to integrate the Nylas Email, Calendar, and Contacts APIs into your app.

This guide will help you get started with the Nylas Python SDK.

Setup your developer account first!

Before following this guide, sign up for a Nylas developer account, and follow our guide to get your developer API keys.

Install

Before you install the SDK, sign up for a Nylas developer account, and follow our guide to get your developer API keys. You will need three values from this guide to run the code examples found here:

  • 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 that is provided when you authenticate an account to your Nylas App

To get started with the Nylas Python SDK, you will need to have pip installed on your machine. From there, you can setup a virtual environment to install the Nylas Python SDK and its dependencies. If you're unfamiliar with how to do this, take a look at the official Python documentation to learn more about setting up pip and virtualenv.

The Nylas Python SDK can be installed with the following command:

pip install nylas

View Authorized Accounts

Once you have the Nylas Python SDK installed, run the following code to view the accounts that are connected to your Nylas app.

from nylas import APIClient

nylas = APIClient(
    CLIENT_ID,
    CLIENT_SECRET
)

# Return all accounts that are connected to your Nylas App
accounts = nylas.accounts.all()
for account in accounts:
    print("Email: {} | Account State: {} | Account ID: {}".format(
        account.get('email'), account.get('sync_state'), account.get('account_id')
    ))

Read the API reference for the accounts endpoint to learn more about the information you can access for accounts. Now, you should be ready to take a look at how to use the Nylas Python SDK to leverage the Nylas email, calendar, and contacts APIs.

Email API

The Nylas Email API makes it easy to integrate Gmail, Outlook, Microsoft Exchange, Office 365 and every other email service provider into your application, and it offers full Create, Read, Update, and Delete (CRUD) operations.

Messages and Threads

The Nylas Email API allows you to work with both messages and threads.

Messages are the fundamental object of the Nylas platform, and the core building block for most email applications. They 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. 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 to match the format of third-party accounts as close as possible.

View Email Messages and Threads

from nylas import APIClient

nylas = APIClient(
    CLIENT_ID,
    CLIENT_SECRET,
    ACCESS_TOKEN,
)

# List the 5 most recent unread threads
for thread in nylas.threads.where(unread=True, limit=5):
    # Print the thread's subject
    print(thread.subject)


# Get the most recent message in expanded view, which includes header information
message = nylas.messages.where(in_='inbox', view='expanded').first()
print(message.subject)
# Print the Nylas global ID for the message
print(message.id)
# Print the service provider ID found in the header
print(message.headers['Message-Id'])

View the API reference for messages and threads to learn more. You can also check out the email API quickstart guide to learn more about the functionality of the Nylas Email API.

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

from nylas import APIClient

nylas = APIClient(
    CLIENT_ID,
    CLIENT_SECRET,
    ACCESS_TOKEN,
)

# Search for an email that is from your friend
messages = nylas.messages.search("from:my.friend@nexample.com")

# .search() returns a list, this command returns the subject line for the most recent result
print(messages[0].get('subject'))

# You can also search threads
threads = nylas.threads.search("A really important thing!")

for thread in threads:
    # Print the subject line for all of the threads that are returned. 
    print thread.get('subject')

View the API reference for messages and threads to learn more. You can also check out the email API quickstart guide to learn more about the functionality of the Nylas Email API.

Send an Email

from nylas import APIClient

nylas = APIClient(
    CLIENT_ID,
    CLIENT_SECRET,
    ACCESS_TOKEN,
)

draft = nylas.drafts.create()
draft.subject = "With Love, from Nylas"
draft.body = "This email was sent using the Nylas Email API. Visit https://nylas.com for details."
draft.to = [{'name': 'My Nylas Friend', 'email': 'swag@nylas.com'}]

draft.send()

View the API reference for sending to learn more. You can also check out the email API quickstart guide to learn more about the functionality of the Nylas Email API.

Calendar API

The Nylas Calendar API acts as a layer of abstraction on top of all calendar providers. The Nylas calendar API offers full Create, Read, Update, and Delete (CRUD) operations for all major calendar providers, with just a few lines of code you can add full-featured scheduling & calendar sync to your application.

Read Calendars and Events

from nylas import APIClient

nylas = APIClient(
    CLIENT_ID,
    CLIENT_SECRET,
    ACCESS_TOKEN,
)

# Most user accounts have multiple calendars where events are stored
calendars = nylas.calendars.all()
for calendar in calendars:
    # Print the name of each calendar and whether or not the calendar is read only
    print("Name: {} | Read Only: {}".format(
        calendar.get('name'), str(calendar.get('read_only'))))

# Get the id of a calendar whose events we want to inspect.
my_calendar = calendars[0].get('id')
# Return the 5 oldest events from a specified calendar and print their titles to the console.
events = nylas.events.where(calendar_id=my_calendar).all(limit=5)
for event in events:
    print(event.get('title')) 

Check out the API reference docs for calendars and events to learn more about the features of these endpoints. You can also take a look at the calendar API quickstart guide to learn more about the functionality of the Nylas calendar API.

Create an Event

from nylas import APIClient

nylas = APIClient(
    CLIENT_ID,
    CLIENT_SECRET,
    ACCESS_TOKEN,
)

event = nylas.events.create()
event.title = "New Years Party!"
event.location = "My House!"
# Event times are set via UTC timestamps
event.when = {"start_time": 1546290000, "end_time": 1546300800}

# Participants can be added via a list of participant subobjects
event.participants = [{"name": "My Friend", 'email': 'my.friend@example.com'}]

# CALENDAR_ID must be the value of a calendar the user account has write access to.
event.calendar_id = CALENDAR_ID

# Event emails are not sent by default
# Enable notify_participants to send an email notification to participants
event.save(notify_participants='true')

Check out the API reference docs for calendars and events to learn more about the features of these endpoints. You can also take a look at the calendar API quickstart guide to learn more about the functionality of the Nylas calendar API.

Contacts API

The Nylas contacts API connects address books and contact databases associated with users' email accounts directly into your application. It offers full Create, Read, Update, and Delete (CRUD) operations to perform bi-directional sync with contact data including addresses, email addresses, birthdays, job titles, and more.

Read Contact Information

from nylas import APIClient

nylas = APIClient(
    APP_ID,
    APP_SECRET,
    ACCESS_TOKEN,
)

contacts = nylas.contacts.all(limit=10)
for contact in contacts:

    # contact.emails returns a defaultdict() object
    # that contains a list of email addresses with their appropriate labels
    email = list(contact.emails.values())[0][0]

    print("Name: {} {} | Email: {} | ID: {}".format(
        contact.given_name, contact.surname, email, contact.id)
          )

Check out the API reference docs for the contacts endpoint to learn more. You can also take a look at the contacts API quickstart guide to learn more about the functionality of the Nylas contacts API.

Create a New Contact

from nylas import APIClient

nylas = APIClient(
    APP_ID,
    APP_SECRET,
    ACCESS_TOKEN,
)

contact = nylas.contacts.create()
# The contact's given name is typically their first name,
# you can specify a last name with 'surname'
contact.given_name = "My Nylas Friend"

# Email address 'type' must be either 'work' or 'personal'
contact.emails['work'] = ['swag@nylas.com']
contact.notes = "Make sure to keep in touch!"

# Phone number type must be one of 'business', 'organization_main',
# 'mobile', 'assistant', 'business_fax', 'home_fax', 'radio', 'car', 'home', or 'pager'
# Google labels 'business' phone numbers as the contact's Work phone number
contact.phone_numbers['business'] = ['(555) 555-5555']

# Web page type must be one of 'homepage', 'profile', 'work', or 'blog'
contact.web_pages['homepage'] = ["https://nylas.com"]

contact.save()

Check out the API reference docs for the contacts endpoint to learn more. You can also take a look at the contacts API quickstart guide to learn more about the functionality of the Nylas contacts API.

Additional Resources

Here are some additional resources for when you're ready to move on.

  • Familiarize yourself with the Nylas Communications Platform through our getting started guide
  • Take a look at the quickstart guides for the Nylas Email, Calendar and Contacts APIs to explore the features of the Nylas Communication Platform.
  • Setup Postman to make it easy to explore the Nylas APIs.
  • When you're ready to start integrating the Nylas Communication Platform into your app, take a look at our app integration guide.
  • Finally, you can always take a look at the API reference to learn about how the Nylas APIs work.

Python SDK


The Nylas Python SDK Quickstart Guide

Suggested Edits are limited on API Reference Pages

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