Version:
Only show these results:

Using Nylas ExtractAI

With Nylas ExtractAI, you can retrieve information about e-commerce orders, shipments, and returns from your users' email inboxes.

🔍 ExtractAI is currently available for Nylas applications in the U.S. data center only. If your application is in the E.U. data center and you want to try ExtractAI, contact Nylas Support.

How ExtractAI works

ExtractAI lets you connect to a user's email inbox and detect messages that contain information about e-commerce orders, shipments, and returns. Nylas inspects the user's incoming messages to determine if they contain related information, and notes that information if they do. You can either query the Order Consolidation API to get the relevant messages, or Nylas can send you notifications so you can take further action.

🔍 Filtering for information happens on the provider side to ensure that your application accesses relevant data only. Enabling ExtractAI does not download the user's entire inbox, or send you notifications about messages that don't contain information about e-commerce orders, tracking, or returns.

ExtractAI only parses an email message if it contains all of the following information:

  • Orders: Order date, order number, and total cost.
  • Shipments: A tracking link, or a tracking number and carrier name.
  • Returns: Email date, refund status, and refund total.

If any of this information isn't included in a message, Nylas does not parse it.

Keep in mind

You should keep the following information in mind as you work with ExtractAI:

  • Don't cache object IDs for later reference, as Nylas updates them as more data comes into a user's inbox. Instead, Nylas recommends you use the unique order_number to reference specific orders, and the tracking_number for shipments.
  • If Nylas can't extract specific data from a message (for example, the shippings.carrier) it returns null.
  • Currently, Nylas doesn't support ExtractAI for grants authenticated using IMAP connectors.

Before you begin

To follow along with the samples on this page, you first need to sign up for a Nylas developer account, which gets you a free Nylas application and API key.

For a guided introduction, you can follow the Getting started guide to set up a Nylas account and Sandbox application. When you have those, you can connect an account from a calendar provider (such as Google, Microsoft, or iCloud) and use your API key with the sample API calls on this page to access that account's data.

You'll also need to set up a provider auth app (Google or Microsoft Azure) and connector with at least the following scopes:

  • Google: gmail.readonly
  • Microsoft: Mail.Read, Mail.Read.Shared (Required if you're extracting data from an organization-specific email account, like a work or school account.)

Activate ExtractAI

First, log in to the Nylas v3 Dashboard, select ExtractAI from the left navigation, and click Enable ExtractAI.

The Nylas Dashboard displaying the ExtractAI page.

⚠️ Nylas automatically creates a Pub/Sub channel when you enable ExtractAI. This channel is subscribed to the ExtractAI triggers (message.intelligence.tracking, message.intelligence.order, and message.intelligence.return) by default, and you don't need to further configure it. Do not delete the channel from the Notifications page. If you do, the ExtractAI APIs will not work.

Now, you can connect to a user's email account by authenticating a grant and begin checking for order and tracking information. You can either make API requests periodically to fetch updated information from Nylas, or get notifications when the user receives messages that meet ExtractAI's requirements.

Set up ExtractAI notifications

ExtractAI can generate notifications when a user receives a message containing information about an e-commerce order, shipment, or return. To set this up...

  1. In the Nylas Dashboard, select Notifications from the left navigation.
  2. Click Create webhook and add a name for the notification settings.
  3. Enter your Webhook URL. This is where Nylas sends webhook notifications. This URL must direct to an HTTPS endpoint that's accessible from the public internet.
  4. Enable the ExtractAI triggers (message.intelligence.tracking, message.intelligence.order, and message.intelligence.return) and click Create webhook.

Nylas sends a confirmation notification to your webhook URL. If you don't receive the confirmation notification, make sure you entered your Webhook URL correctly.

When your webhook is set up, Nylas automatically starts generating notifications for messages that contain order, shipment, or return information. See the Notification schemas documentation for schema examples.

🔍 Nylas extracts data for grants authenticated before you set up ExtractAI webhooks only. If you want to get up to 30 days of historical email messages, you must authenticate your users after you configure webhooks for ExtractAI.