Clean Conversation in Nylas v3

✨ The v3 Clean Conversation endpoint is new as of Nylas v3.1.0!

The Clean Conversation endpoint uses neural language processing and machine learning to remove all extra information (for example, images and attachments) from an email message and return only the information that you need.

ℹ️ Clean Conversations is available for Plus plans only. Not available for Calendar-only plans.

How Clean Conversation works

When you make a request to the Clean Conversation endpoint, Nylas uses advanced neural language processing and machine learning models to clean structured email messages. It extracts relevant content using a machine learning model, and caches the results to reduce response times.

Configuration options

The Clean Conversation endpoint offers multiple options to control how Nylas parses email messages:

ignore_links: When true, removes links in the message or signature. Defaults to true.
ignore_images: When true, removes images from the message or signature. Defaults to true.
images_as_markdown: When true, Nylas returns images as Markdown links. Defaults to false.
ignore_tables: When true, removes tables from the message or signature. Defaults to true.
remove_conclusion_phrases: When true, removes phrases such as "Best" and "Regards" in the signature. Defaults to true.

You set each of these options on a per-request basis, so no need to worry about deciding how you want all of your cleaned email messages to look. For more information, see the Clean Conversation reference documentation.

Before you begin

Before you start making Clean Conversation requests, you need the following prerequisites:

A v3 Nylas application.
A working authentication configuration. Either...
- A Nylas Dashboard v3 Sandbox application which includes a demonstration auth config,
  OR
- A v3 provider auth app (Google or Azure), and a connector for that auth app.
A Google or Microsoft grant with at least the following scopes:
- Google: gmail.readonly
- Microsoft: Mail.Read

Clean email messages

To clean an email message, make a PUT /v3/grants/{grant_id}/messages/clean request that includes the IDs of up to 20 messages you want to update. You can also specify whether Nylas should ignore included links, images, and more while cleaning the message.

Nylas returns the parsed email message as part of the message object. All of the extra HTML content is stripped out, leaving only the message text.

Request
Response (JSON)

curl --location --request PUT 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/messages/clean' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <NYLAS_API_KEY_OR_ACCESS_TOKEN>' \
  --data '{
    "message_id": ["18df98cadcc8534a"],
    "ignore_links": false,
    "ignore_images": false,
    "images_as_markdown": true
    "ignore_tables": true,
    "remove_conclusion_phrases": true,
  }'

{
  "request_id": "5fa64c92-e840-4357-86b9-2aa364d35b88",
  "data": [{
    "body": "<div dir=\"ltr\"><div>Hello, I just sent a message using Nylas! <br></div><img src=\"cid:ii_ltppe5ph0\" alt=\"Nylas-Logo-Stacked-Blue_.png\" width=\"540\" height=\"464\"><br><div dir=\"ltr\" class=\"gmail_signature\" data-smartmail=\"gmail_signature\"><div dir=\"ltr\"></div></div></div>\r\n",
    "cc": [{
      "name": "Arya Stark",
      "email": "[email protected]"
    }],
    "date": 1635355739,
    "attachments": [{
      "is_inline": true,
      "id": "v0:TnlsYXMtTG9nby1TdGFja2VkLUJsdWVfLnBuZw==:aW1hZ2UvcG5nOyBuYW1lPSJOeWxhcy1Mb2dvLVN0YWNrZWQtQmx1ZV8ucG5nIg==:26044",
      "grant_id": "<NYLAS_GRANT_ID>",
      "filename": "Nylas-Logo-Stacked-Blue_.png",
      "content_type": "image/png; name=\"Nylas-Logo-Stacked-Blue_.png\"",
      "content_disposition": "inline; filename=\"Nylas-Logo-Stacked-Blue_.png\"",
      "content_id": "ii_ltppe5ph0",
      "size": 26044
    }],
    "folders": [
      "8l6c4d11y1p4dm4fxj52whyr9",
      "d9zkcr2tljpu3m4qpj7l2hbr0"
    ],
    "from": [{
      "name": "Daenerys Targaryen",
      "email": "[email protected]"
    }],
    "grant_id": "41009df5-bf11-4c97-aa18-b285b5f2e386",
    "id": "5d3qmne77v32r8l4phyuksl2x",
    "object": "message",
    "reply_to": [{
      "name": "Daenerys Targaryen",
      "email": "[email protected]"
    }],
    "snippet": "Hello, I just sent a message using Nylas!",
    "starred": true,
    "subject": "Hello from Nylas!",
    "thread_id": "1t8tv3890q4vgmwq6pmdwm8qgsaer",
    "to": [{
      "name": "Jon Snow",
      "email": "[email protected]"
    }],
    "unread": true,
    "conversation": "Hello, I just sent a message using Nylas!"
  }]
}

Before and after Clean Conversation request

Before

After

Unsubscribe  \n\n  \nHi there,\n\nNylas API v3 is now generally available! The new infrastructure introduces:  \n\n  * Instant email and event functionality, boosting performance, security, and scalability.\n  * Simplified integrations such as API keys for auth, enhanced webhooks, Microsoft Graph, and more to streamline engineering efforts even further.\n  * New email features such as Bounce Detection, Smart Compose, Scheduled Send, and custom domain for email tracking links to improve email deliverability and efficiency.\n\nCheck out Nylas docs and join our webinar on Feb 15 to learn more, and start\nmigrating today!\n\nHave questions about migrating? Contact your dedicated Nylas customer success\nmanager (CSM) or email [email protected].  \n\n© 2024 Nylas Inc. All rights reserved.\n\nPrivacy Policy | Copyright | Unsubscribe\n\n2100 Geng Rd. #210, Palo Alto, CA 94303

Return plain text

The following request removes all images, tables, and links from an email message. Any images will instead be returned as part of the Attachments object.

curl --location --request PUT 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/messages/clean' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>' \
  --data '{
    "message_id": ["<MESSAGE_ID>"],
    "ignore_links": true,
    "ignore_images": true,
    "images_as_markdown": true
    "ignore_tables": true,
    "remove_conclusion_phrases": true,
  }'

Clean email messages with images

When you submit an email message that contains images to the Clean Conversation endpoint, you can choose how Nylas handles the images. If you want to return them, set ignore_images: false. If you want to return the image tags as Markdown links, set images_as_markdown: true and ignore_images: false.

Nylas returns inline images as part of the cleaned message and includes a content ID (cid), as in the following examples:

Inline image: "conversation": "<img src='cid:1781777f666586677621' />\n\nImage from Gmail"
Inline image as Markdown: "conversation": "![Nylas logo](cid:1781777f666586677621)\n\nImage from Gmail"

🔍 The content ID is an internal ID for Nylas. If you want to download an image from a cleaned email message, use the corresponding ID from the Attachments object in the response instead.

Nylas returns some inline images with a link to the original image source, if the link is available. If the link isn't available, Nylas returns the cid.

Nylas doesn't return image attachments as part of the cleaned message. You can find information about attached images in the Attachments object that Nylas returns.

Download images

To download an image that was included in a cleaned email message, make a Download Attachment request that includes the attachment ID.

curl --request GET \
  --url https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/attachments/<ATTACHMENT_ID>/download?message_id=<MESSAGE_ID> \
  --header 'Authorization: Bearer <NYLAS_API_KEY>'

Keep in mind

You should keep the following things in mind as you work with the Clean Conversation endpoint:

If you pass a forwarded email message in your request, Nylas returns an empty message.
The Clean Conversation endpoint currently supports English language text only.
The Nylas SDKs currently don't support the Clean Conversation endpoint.
You currently cannot use webhooks with the Clean Conversation endpoint.