Clean Conversation in Nylas
The Clean Messages endpoint uses language processing and machine learning to parse messages. Nylas removes all extra information (for example, images and attachments) and returns only the information that you need. You can use this clean data to train machine learning models with email data, trigger automations, and more.
How Clean Conversation works
When you make a request to the Clean Messages endpoint, Nylas uses advanced machine learning models to clean structured messages. It extracts relevant content and caches the results to reduce response times. You can use these cleaned messages to train other machine learning models with your email data, trigger automations, create chat-like views of email threads, and more.
Nylas removes all extraneous information (such as HTML <script> and <style> tags) and returns the cleaned body text in the conversation field. You can use the following configuration parameters to further specify the information Nylas returns:
ignore_links: Whentrue, removes links in the message or signature. Defaults totrue.ignore_images: Whentrue, removes images from the message or signature. Defaults totrue.images_as_markdown: Whentrue, Nylas returns images as Markdown links. Defaults tofalse.ignore_tables: Whentrue, removes tables from the message or signature. Defaults totrue.remove_conclusion_phrases: Whentrue, removes phrases such as "Best" and "Regards" in the signature. Defaults totrue.html_as_markdown: Whentrue, converts the message to markdown. Defaults tofalse.
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
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 - EWS:
ews.messages
Clean messages
Make a Clean Messages request that includes the IDs of up to 20 messages. Nylas returns the cleaned message in the conversation field and any images in the attachments object.
curl --request PUT \
--url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/messages/clean' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json, application/gzip' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
--data '{
"message_id": ["<MESSAGE_ID>"],
"ignore_links": true,
"ignore_images": true,
"images_as_markdown": false,
"ignore_tables": true,
"remove_conclusion_phrases": true,
"html_as_markdown": false
}' {
"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.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": "Leyah Miller",
"email": "leyah@example.com"
}],
"date": 1635355739,
"attachments": [{
"is_inline": true,
"id": "<ATTACHMENT_ID>",
"grant_id": "<NYLAS_GRANT_ID>",
"filename": "Nylas-Logo.png",
"content_type": "image/png; name=\"Nylas-Logo.png\"",
"content_disposition": "inline; filename=\"Nylas-Logo.png\"",
"content_id": "<CID>",
"size": 26044
}],
"folders": [
"<FOLDER_ID>",
"<FOLDER_ID>"
],
"from": [{
"name": "Nylas",
"email": "nylas@example.com"
}],
"grant_id": "<NYLAS_GRANT_ID>",
"id": "<MESSAGE_ID>",
"object": "message",
"reply_to": [{
"name": "Nylas",
"email": "nylas@example.com"
}],
"snippet": "Hello, I just sent a message using Nylas!",
"starred": true,
"subject": "Hello from Nylas!",
"thread_id": "<THREAD_ID>",
"to": [{
"name": "Nyla",
"email": "nyla@example.com"
}],
"unread": true,
"conversation": "Hello, I just sent a message using Nylas!"
}]
} Before and after Clean Message 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 notifications, 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 customeronboarding@nylas.com. \n\n© 2024 Nylas Inc. All rights reserved.\n\nPrivacy Policy | Copyright | Unsubscribe\n\n2100 Geng Rd. #210, Palo Alto, CA 94303
Return cleaned message as Markdown
When you set images_as_markdown and html_as_markdown to true in your request, Nylas formats the cleaned message to Markdown and returns it in the email_as_markdown field.
Clean messages with images
When you specify a message that contains images in a Clean Message request, you can choose how Nylas handles the images. If you want to return them, set ignore_images to false. If you want to return the image tags as Markdown links, set images_as_markdown to true and ignore_images to false.
Nylas returns inline images in the conversation field as part of the cleaned message, and includes their content ID (cid):
- Inline image:
"conversation": "<img src='cid:1781777f666586677621' />\n\nImage from Gmail" - Inline image as Markdown:
"conversation": "\n\nImage from Gmail"
📝 The content ID is an internal Nylas ID. If you want to download an image from a cleaned message, use the corresponding id from the attachments object in the response instead.
Nylas returns some inline images with a link to the original source, if available. If the link isn't available, Nylas returns the cid.
Nylas doesn't return image attachments as part of a cleaned message. You can find information about attached images in the attachments object.
Download images from cleaned message
To download an image that was included in a cleaned message, make a Download Attachment request that includes the attachment and message IDs. Nylas returns the image as a binary data blob.
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
Keep the following things in mind as you work with the Clean Message endpoint:
- Nylas currently detects English-language conclusion phrases only when you set
remove_conclusion_phrasestotrue. - Nylas removes any reply and forward content from the message, and returns only the latest message in the thread.
- You cannot currently use notifications with the Clean Message endpoint.