The Nylas Neural API: Lean-Code Machine Learning for Communications and Scheduling

8 min read

Long time Nylas fans might remember when we acquired June.ai earlier this year: a company that built an email inbox app powered by Machine Learning (ML) to provide unique insight about users’ email and enable more intelligent email interactions. Our core products are backend API services for developers, so we wanted to turn the excellent user-facing features June.ai engineers built into simple solutions that would let developers access advanced ML capabilities with only a few lines of code.

We recently launched the Neural API: a back-end service that enables developers to leverage advanced ML capabilities for any data connected to the Nylas Platform. This article will examine why we built this and how we’re using it to solve common problems developers face when working with their users’ email inboxes.

Why Does ML Have to Be So Tough?

ML technologies are notoriously difficult to use because of the relatively substantial amount of infrastructure inherent to their operation. First, you need to acquire a set of training data either by generating it yourself, purchasing it from a company specializing in trained ML models, or downloading it from public repositories. There is a substantial amount of manual effort required to classify and annotate training data, which compounds the difficulty of this work, particularly for niche use cases.

Once you’ve prepared your training data, you need powerful hardware to handle an immense number of simultaneous operations while accessing large amounts of data stored in memory. You can choose to purchase hardware yourself or use one of the many developer infrastructure service companies like AWS, Google, and Azure who offer priced web services based on processing time. However, all of these options can be costly and create unique complexities.

Finally, the world is continually changing, and your ML models will need to evolve to meet dynamic environments. You’ll need to establish success metrics for your models that can be quantified and tracked to ensure their output is consistently reliable. Ongoing training and maintenance are practically guaranteed when you rely on ML models.

The combination of these factors puts ML capabilities out of reach for most small development teams, leaving an opportunity for companies like Nylas to build solutions that serve their needs. Our ultimate goal with the Neural API is to make ML as accessible as possible to developers building communications and scheduling integrations.

The Intelligent Approach to Email, Calendar, and Contacts

Nylas builds connectivity APIs that enable developers to integrate their users’ email, calendar, contacts accounts into an app. There are quite a few situations where ML capabilities would be useful for someone working with this data, but the cost of building ML infrastructure from scratch often outweighs the benefits it creates, particularly for simple use cases. Nylas took our first major step towards democratizing ML capabilities for email and scheduling integrations with the Neural API. 

The Neural API is the intelligence center of the Nylas Platform; it provides machine learning capabilities you can apply to any data connected to Nylas. The Neural API abstracts complex ML techniques into functional capabilities you can leverage in minutes. Developers don’t need to become experts at building and training custom machine learning models to implement functionality like categorization, OCR, and parsing unstructured data. 

Our first major milestone in this effort is a new collection of API endpoints that drastically reduce the effort required to extract human-to-human conversation from an email inbox. This concept is a core component of a wide range of email integrations, so we decided it’s the best place to focus our ML capabilities. Let’s dive in to take a close look at how it works!

Extract Human-to-Human Interactions From Email Inboxes

An email inbox can be as complicated as its user’s life and typically includes a wide range of data associated with their online interactions. However, the most important emails are often those that involve other people, so we want to simplify the process of extracting human to human conversations from users’ email inboxes. To this end, we have three inaugural endpoints for the Neural API:

  • Categorizor – Classify incoming emails such as human-to-human, machine-to-human, out-of-office and bounced emails with a single API call.
  • Clean Conversations –  Extract email bodies as text so that you can train ML models with email data, trigger automation, create chat-like views of email and more.
  • Signature Extraction – Automatically detect and parse key information found in email signatures and returns the information in JSON with a single API call.

We decided to create the Neural API as the home for these capabilities because they represent a fundamental shift in designing and planning our APIs. Instead of merely connecting developers to their users’ email, calendar, and contacts accounts, we also provide tools that let you transform that data into much more meaningful representations. We think that human conversation is one of the most important aspects of a peoples’ online life, so we wanted to make it much easier for developers to access rich communications data from their users’ email inboxes.Now, let’s take a close look at how these new endpoints work.

Categorize Email by Human Conversation

Before you can extract a conversation or a signature from an email, you need to determine if a human sent it in the first place. The Categorize endpoint takes care of this by assigning one of two categories to any email message it’s run for: 

  • conversation – A human-to-human email conversation.
  • feed – An email generated by an automated process such as marketing campaigns, password resets, user account updates, etc.

To run this function, make a PUT request to the categorize endpoint, passing the id of the message you want to categorize.

curl -X PUT 'https://api.nylas.com/neural/categorize' 
  -H 'Authorization: Bearer ACCESS_TOKEN' 
-d '{
    "message_id":"sfgdfgrt"
}'

The Neural API will respond with the message object and include a new category attribute that indicates the message’s category (all JSON examples in this article are abbreviated for readability):

{
    "id": "sfgdfgrt",
    "object": "message",
    "subject": "Welcome to the team!",
    "thread_id": "cvspdfg",
    "category" : "conversation" 
}

An important thing to remember with the Neural API is that it works with data connected through one of the Nylas Connectivity APIs. Whenever you make a PUT request to the categorize endpoint, Nylas alters the existing email message, the thread it’s a part of, and all other messages in the thread to include the appropriate category value. All future GET requests for this, and all related messages will return the proper category attribute.

It also means that you can now filter GET requests to theThreads andMessages endpoints to only return emails that are part of human conversations:

curl -X GET 'https://api.nylas.com/threads?category=conversation' 
-H 'Authorization: Bearer ACCESS_TOKEN'
curl -X GET 'https://api.nylas.com/messages?category=conversation' 
-H 'Authorization: Bearer ACCESS_TOKEN' 

Extract Conversation Text and Signature Details

Now that we’ve seen how to categorize emails into human conversations let’s take a look at the Neural API’s Conversation and Signature endpoints.

You can make a PUT request to the Conversation endpoint to create a new value for the message’s conversation attribute. This attribute will contain the raw text of human conversation. I.e., the exact text that the sender added to the email conversation. It will filter out all other content, such as signatures, HTML, and duplicate body content from previous email replies:

curl -X PUT 'https://api.nylas.com/neural/conversation' 
  -H 'Authorization: Bearer ACCESS_TOKEN' 
-d '{
    "message_id":"sfgdfgrt"
}'

The Signature endpoint works in a very similar manner and creates a value for the signature attribute. This attribute stores the raw text of the sender’s signature:

curl -X PUT 'https://api.nylas.com/neural/signature' 
  -H 'Authorization: Bearer ACCESS_TOKEN' 
-d '{
    "message_id":"sfgdfgrt"
}'

If you run both of these requests for a message, you’ll end up with a message object that now includes values for these attributes (the example is abbreviated for readability):

curl -X GET 'https://api.nylas.com/messages/sfgdfgrt' 
-H 'Authorization: Bearer ACCESS_TOKEN'

{
    "id": "sfgdfgrt",
    "object": "message",
    "subject": "Welcome to the Team",
    "thread_id": "cvspdfgj6346d",
    "category" : "conversation",
    "conversation": "We're super happy to have you onboard! Let me know if you have questions",
    "signature":"Ada Lovelace nSenior Researcher nLondon, England" 
}

More Machine Learning Capabilities On The Way

Human conversation is only the first step Nylas is taking to make email, calendar, and contacts integrations more intelligent. As part of the Neural API launch, we’re also pleased to announce early access to our new OCR endpoint, making it simple to extract raw text from images, pdfs, and other file attachments. With Nylas, your success is our success, so we’re here to help you get the most out of your communications and scheduling integration.

If you’re interested in learning more about the Neural API and other upcoming features, reach out to a platform specialist to get the conversation started. You can also subscribe to our blog to get updates about all the new features we have in the pipeline.

Related resources

How to Solve Webhook Integration Challenges with PubSub Notification Channel

Key Takeaways This article addresses the challenges of webhook integration and introduces the PubSub Notification…

How to Send Emails Using an API

Key Takeaways This post will provide a complete walkthrough for integrating an email API focused…

How to build a CRM in 3 sprints with Nylas

What is a CRM? CRM stands for Customer Relationship Management, and it’s basically a way…