Using Nylas ExtractAI

With Nylas ExtractAI, you can retrieve order details and tracking information about e-commerce purchases from your end users’ email inboxes.

Note

🔍 ExtractAI is currently available for Nylas applications in the U.S. region only.

This page explains how to use ExtractAI:

• Activate ExtractAI.
• Set up ExtractAI notifications.
• Make calls to the Order Consolidation API.

How ExtractAI works

ExtractAI allows you to connect to a user’s email inbox and detect email messages that contain information about e-commerce orders and shipments. Nylas inspects the user’s incoming email messages to determine if they contain order or shipment 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.

Note

🔍 Filtering for information happens on the provider side to ensure that your application accesses data about e-commerce orders and shipments only. Enabling ExtractAI does not download the end user’s entire inbox, or send you notifications about email messages that don’t contain order or shipment information.

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

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

Nylas only sends notifications and returns API results for email messages containing the above information. If any of this information isn’t included in an email message, Nylas does not parse it as an order or shipment email.

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 order and shipment information comes into an end 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 for an order or shipment (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 instructions on this page, you need to complete the following prerequisites:

• Sign up for a Nylas developer account.
• Create a v3 Nylas application or Sandbox.
• Create a provider auth app for your development, staging, or production application (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, enable ExtractAI for your application:

1. Log in to the Nylas v3 Dashboard and select your application.
2. Click Activate ExtractAI > Enable ExtractAI.

Caution

⚠️ Nylas automatically creates a Pub/Sub channel when you enable ExtractAI. This channel is subscribed to the ExtractAI triggers (message.intelligence.tracking and message.intelligence.order) 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 an end 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 end user receives email messages that meet ExtractAI’s requirements.

Set up ExtractAI notifications

ExtractAI can generate notifications when a user receives an email message containing information about an e-commerce order or shipment. 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 (also called a “callback URL”). This URL must direct to an HTTPS endpoint that’s accessible from the public internet.
4. Enable the ExtractAI triggers (message.intelligence.tracking and message.intelligence.order).
5. 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 email messages that contain order or shipment information. See the Notification schemas documentation for schema examples.

Note

🔍 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 end users after you configure webhooks for ExtractAI.