Understand Zoho CRM’s Deal Prediction Mechanism and how to use the Link/Unlink Deal Email APIs compa
Hi All,
Welcome back to another week of Kaizen!
Emails are a core channel for customer communication in any CRM system. In Zoho CRM, emails can be associated with records across multiple modules.
In this post, we will focus on email associations with the records of the Deals Module.
Deal Prediction Mechanism
In Zoho CRM, Deal Prediction Mechanism automatically associates emails with the contact's deal.
When an email is received for a Contact:
- If the contact has only one open deal, the email is linked to that deal.
- If the contact has multiple open deals, the email is linked to the most recently modified deal, provided the deal is not closed-lost.
- If there are no valid open deals, the email is not linked to any deal.
While deal prediction simplifies email association, certain scenarios require manual control over how emails are linked to deals.
In such cases you might want to:
- Correct an incorrect association.
- Attach an email to a deal that the prediction could not infer.
Zoho CRM provides two focused APIs for this:
These APIs do not create emails — they simply manage associations.
Link Deal to Emails API
The Link Deal to Emails API lets you programmatically attach one or more emails to a specific deal.
Endpoints
POST /Contacts/{contacts_record_ID}/Emails/actions/link_record
POST /Contacts/{contacts_record_ID}/Emails/{message_ID}/actions/link_record
Sample request for linking a single email
Request URL
POST
https://www.zohoapis.com/crm/v8/Contacts/5843104000005878180/Emails/b9c24f3b403f8c3b197f2b8ab967c104d597ab1b968e3b8a59437278f4f26f77/actions/link_record
Input JSON
{ "Emails": [ { "linked_record": { "module": { "api_name": "Deals", "id": "5843104000000003735" }, "name": "Travel Insurance", "id": "5843104000004382122" }, "owner": { "name": "Patricia Boyle", "id": "5843104000000424672" } } ] } |
You can also link a single email by mentioning message id in the request body in the endpoint POST /Contacts/{contacts_record_ID}/Emails/actions/link_record
Request URL
POST
https://www.zohoapis.com/crm/v8/Contacts/5843104000005878180/Emails/actions/link_record
Input JSON
{ "Emails": [ { "message_id": "b9c24f3b403f8c3b197f2b8ab967c104d597ab1b968e3b8a59437278f4f26f77", "linked_record": { "module": { "api_name": "Deals", "id": "5843104000000003735" }, "name": "Travel Insurance", "id": "5843104000004382122" }, "owner": { "name": "Patricia Boyle", "id": "5843104000000424672" } } ] } |
Response
{ "Emails": [ { "code": "SUCCESS", "details": { "message_id": "b9c24f3b403f8c3b197f2b8ab967c104d597ab1b968e3b8a59437278f4f26f77" }, "message": "email has been linked with the deal successfully", "status": "success" } ] } |
Sample request for linking multiple emails
Input JSON
{ "Emails": [ { "owner": { "name": "Patricia Boyle", "id": "5843104000000424672" }, "message_id": "8937fb892cc6f15b95bc22ecb91b6f85e9f60916ef9314d484543df546f09ad1", "linked_record": { "module": { "api_name": "Deals", "id": "5843104000000003735" }, "name": "Travel Insurance", "id": "5843104000004382122" } }, { "owner": { "name": "Patricia Boyle", "id": "5843104000000424672" }, "message_id": "6622e532084a2c329b44f4d7c58a93bb2f616d21e1e73cc1e9cc71d24ef6b5f5", "linked_record": { "module": { "api_name": "Deals", "id": "5843104000000003735" }, "name": "Travel Insurance", "id": "5843104000004382122" } } ] } |
Response
{ "Emails": [ { "code": "SUCCESS", "details": { "message_id": "8937fb892cc6f15b95bc22ecb91b6f85e9f60916ef9314d484543df546f09ad1" }, "message": "email has been linked with the deal successfully", "status": "success" }, { "code": "SUCCESS", "details": { "message_id": "6622e532084a2c329b44f4d7c58a93bb2f616d21e1e73cc1e9cc71d24ef6b5f5" }, "message": "email has been linked with the deal successfully", "status": "success" } ] } |
Keys
- owner (JSON object, mandatory): Specify the details of the user whose email you want to link. It consists of the following keys
- name: Specify the name of the user whose email you want to link.
- id: Specify the ID of the user whose email you want to link.
- message_id (string, mandatory when message_id is not mentioned in the endpoint): Specify the unique message ID of the email to which the deal will be linked. You can obtain message ID of a record through Get Emails of a Record API. [/crm/[version}/Contacts/{contacts_record_ID}/Emails]
- linked_record(JSON object, mandatory): Specify the details of the Deals record to be linked to the email. It consists of the following mandatory keys
- module(JSON object, mandatory): Specify the details of the Deals module. It consists of the following keys
- api_name: Specify the API name of the Deals module.
- id: Specify the ID of the Deals module.
- name: Specify the name of the Deals record that the email must be linked to. Refer to the field: Deal_Name in the Get Records API for the Deals record. [/crm/[version}/Deals/{deals_record_ID}] in the Get Records API.
- id: Specify the ID of the Deals record that the email must be linked to.
Notes
- An email can be linked to only one deal at a time.
- You can link multiple emails in a single request by providing multiple Emails objects in the request body.
- This API works only with existing email records.
Unlink Deal from Emails API
If an email is linked to the wrong deal through deal prediction or the Link Deal to Emails API, you can use the Unlink Deal from Emails API.
Endpoints
DELETE /Contacts/{contacts_records_ID}/Emails/actions/link_record?owner_id={owner_ID}&message_ids={message_ID1},{message_ID2},..
DELETE /Contacts/{contacts_records_ID}/Emails/{message_id}/actions/link_record?owner_id={owner_ID}
Sample request for unlinking multiple emails
Request URL
DELETE
https://www.zohoapis.com/crm/v8/Contacts/5843104000000425349/Emails/actions/link_record?owner_id=5843104000000424672&message_ids=8937fb892cc6f15b95bc22ecb91b6f85e9f60916ef9314d484543df546f09ad1,6622e532084a2c329b44f4d7c58a93bb2f616d21e1e73cc1e9cc71d24ef6b5f5
Response
{ "Emails": [ { "code": "SUCCESS", "details": { "message_id": "8937fb892cc6f15b95bc22ecb91b6f85e9f60916ef9314d484543df546f09ad1" }, "message": "email has been unlinked from the deal successfully", "status": "success" }, { "code": "SUCCESS", "details": { "message_id": "6622e532084a2c329b44f4d7c58a93bb2f616d21e1e73cc1e9cc71d24ef6b5f5" }, "message": "email has been unlinked from the deal successfully", "status": "success" } ] } |
Mandatory Parameters
- owner_ID Specify the unique ID of a user whose email you want to unlink.
- message_ids Specify the unique message IDs of the emails which you want to unlink. You can obtain message IDs of a record through Get Emails of a Record API.
Example use case
- Prediction linked an email to deal A.
- Your business logic determines that the email belongs to deal B.
- Call the Unlink API.
- Call the Link API with the correct deal.
Key behavior
- Unlinking does not delete the email.
- Email remains visible under the Contact.
- Only the Deal association is removed.
Link Deal to Emails API v/s Associate Email with a Record API
At first glance, these two APIs may look similar because both are about emails and their record associations. However, they serve different purposes.
The Associate Email with a Record API is used to create and store an email in Zoho CRM and associate it with a record. You must provide the complete email details such as From, To, CC, Subject, Content, attachments, and the original message id. In short, this API is used when the email does not yet exist in Zoho CRM and needs to be logged as a new email record and associated with a records in modules like Leads, Contacts, Deals etc.
On the other hand, the Link Deal to Emails API does not create an email. Instead, it works only with emails that already exist in CRM. It allows you to associate or re-associate a Contact's emails with a Deal. It is primarily used to control which deal an existing email should be linked to.
- Use Associate Email API when you want to log a new email into CRM and associate it to a record.
- Use Link/Unlink Deal APIs when you want to manage the Deal association of an existing email.
Key differences
Aspect | Associate Email API | Link Deal APIs |
Creates Email Record | Yes | No |
Requires email content | Yes | No |
Works on existing emails | No | Yes |
Purpose | Log emails into CRM and associated to a record | Manage associations between deal and contact's emails. |
Zoho CRM’s Deal Prediction Mechanism is designed to reduce manual effort, but APIs give developers the flexibility to handle complex business workflows.
- Deal Prediction handles the common association scenarios.
- Link and Unlink APIs provide manual control over Email-Deal associations.
- Associate Email with a Record API brings external emails into Zoho CRM.
Used together, these features ensure emails are always associated under the right Deal.
We hope that you find this post on Email-Deal Associations useful.
If you have any feedback, please let us know in the comments, or reach out to us via support@zohocrm.com.
Previous Kaizen Post: Kaizen #228 - Process Large-Scale Migrated Data Using Catalyst Solutions| Kaizen Collection: Directory
Access your files securely from anywhere
Zoho FSM Video Tutorials
Centralize Knowledge. Transform Learning.
All-in-one knowledge management and training platform for your employees and customers.
New to Zoho Recruit?
Zoho Developer Community
New to Zoho LandingPage?
Zoho LandingPage Resources
New to Zoho Survey?
New to Zoho CRM Plus?
Deliver unforgettable customer experiences
New to Zoho CRM Plus?
Deliver unforgettable customer experiences
New to Zoho Marketing Plus?
Everything you need to run your marketing
New to Zoho Marketing Plus?
Everything you need to run your marketing
New to Bigin?
Topic Participants
Mable Mary M P
DJ
Sticky Posts
Announcing the new SKILL.md for Zoho CRM and the updated OAS repository!
We are introducing a new zoho-crm skill to make working with Zoho CRM Developer tools (like APIs, functions, widgets, client scripts, queries etc) easier and faster, with the help of AI in your preferred AI harness like Claude Code, Codex, Cursor, VSCodeKaizen #261 : Using Zoho CRM Skill to generate complex COQL queries
Hello everyone, In the previous Kaizen posts, we introduced the zoho-crm SKILL.md and discussed how it can help you when you are working with Zoho CRM APIs and Client Script. In this Kaizen, we will focus on using the Zoho CRM `SKILL.md` with GitHub CopilotKaizen #256 - Build an Arrival Readiness Web Tab in Zoho CRM
Hi everyone! Welcome back to the Kaizen series! In the post, we discuss a use case in hospitality industry: how an Arrival Readiness web tab widget can be used to let reception staff identify and resolve issues before arrival of guests. Use case In theKaizen #198: Using Client Script for Custom Validation in Blueprint
Nearing 200th Kaizen Post – 1 More to the Big Two-Oh-Oh! Do you have any questions, suggestions, or topics you would like us to cover in future posts? Your insights and suggestions help us shape future content and make this series better for everyone.Kaizen #226: Using ZRC in Client Script
Hello everyone! Welcome to another week of Kaizen. In today's post, lets see what is ZRC (Zoho Request Client) and how we can use ZRC methods in Client Script to get inputs from a Salesperson and update the Lead status with a single button click. In this
New to Zoho TeamInbox?
Zoho TeamInbox Resources
Zoho CRM Plus Resources
Zoho Books Resources
Zoho Billing Resources
Zoho Projects Resources
Zoho Sprints Resources
Qntrl Resources
Zoho Creator Resources
Zoho CRM Resources
Design. Discuss. Deliver.
Zoho Show Resources
Get Started. Write Away!
Writer is a powerful online word processor, designed for collaborative work.
Zoho CRM コンテンツ
-
オンラインヘルプ
-
Webセミナー
-
機能活用動画
-
よくある質問
-
Ebook
-
-
Zoho Campaigns
- Zoho サービスのWebセミナー
その他のサービス コンテンツ
Nederlandse Hulpbronnen
ご検討中の方
Recent Topics
Announcing new features in Trident for Windows (v.1.43.5.0)
Hello Community! This release includes a collection of enhancements and feature updates aimed at making your email and collaboration experience smoother. Let’s dive into what’s new! Zoho Desk email notifications as Smart Mail. Zoho Desk Smart Mail isHow to Manage Two GST Numbers / Two Companies in a Single Zoho Inventory Organization?
Hi Team, We currently have two separate legal entities: A Proprietorship Firm with its own GSTIN A Private Limited Company with a different GSTIN However, operationally, both companies deal with the same products, and we would like to manage the physicalHow To Implement an Auto-Check-out Feature for Attendance?
If an employee forgets to check out, the system should automatically check out the employee at 6:30 PMConvert an Existing Single Item into an Item with Variants
Hello Zoho Team, Introducing variants is a great addition to Zoho Inventory. However, we would like to request an option to convert an existing single item into an item with variants. For example, Item A initially comes in only one colour, so we createIP Address List > Sigma
We have developed a ZohoCRM extension that utilizes API calls to our server from Deluge scripts and Widgets. Our API server has IP restrictions in place. To ensure successful communication, we require a list of IP addresses utilized by Zoho's platformDefault Country list suggestions on CRM is different then on Book; how do/did others address this?
So I already have a support ticket in for this and waiting for a response but figured I'd ask the community also to see if others experienced the same problems and/or how they went about addressing it because sometimes I feel like I'm going crazy withObject-level edit permissions
Hi, we are currently running into a limitation with permissions inside larger workspaces. Our use case is a central Analytics workspace that contains many tables, Query Tables, reports and dashboards used by different teams. We would like to allow certainConvert Sales order to Delivery Challan
Dear Developer Team, In Zoho books we cannot convert sales order into delivery challan before making invoices. As a service business we have to get the delivery note signed then only we can make the invoice. In Some cases we don't receive a purchase orderWhat's New in Zoho Inventory | September 2026
Hello users, September brings a range of new features and enhancements across Zoho Inventory. From improved inventory operations and reporting capabilities to greater customization, automation, and enhancements to Delivery Challans, there’s plenty toMirror Component in Zoho CRM: Access real-time related data without leaving your record
Hi everyone, This feature is now available for the JP, CA, SA, UAE, and AU DCs. We're excited to bring to you Zoho CRM's mirror component, which presents relevant data on a record's details page and keeps everything users need in one place without havingAll new Address Field in Zoho CRM: maintain structured and accurate address inputs
Availability Update: 29 September 2025: It's currently available for all new sign-ups and for existing Zoho CRM orgs which are in the Professional edition exclusively for IN DC users. 2 March 2026: Available to users in all DCs except US and EU DC. 24Create custom rollup summary fields in Zoho CRM
Hello everyone, In Zoho CRM, rollup summary fields have been essential tools for summarizing data across related records and enabling users to gain quick insights without having to jump across modules. Previously, only predefined summary functions wereHow to mix different types of inputs (such as dropdown list and textbox)
Hi, I'm creating a form called "Room Reservations" for a company. I created a "table" using "Matrix Choice". I created "Room 1", "Room 2" and "Room 3" with the "Questions". I would then like to create two columns with the "Answers", one called "Department"Feature Request: Render Markdown (.md) files in Zoho Cliq
Hi, We regularly share Markdown (.md) files in Zoho Cliq. However, when we open these files in Cliq, the content does not render as Markdown—it displays as plain text. This forces us to copy/paste the content into an external Markdown viewer to read itDealing With One-Time Customers on Zoho Books
Hello there! I am trying to figure out a way to handle One-Time customers without having to create multiple accounts for every single one on Zoho Books. I understand that I can create a placeholder account called "Walk-In Customer", for example, but ICash Basis VAT RETURN REPORT Required in Saudi Arabia
Zoho Books in Saudi Arabia not showing TAX RETURNS report on CASH Basis.. It only showing accrual basis. Oforur requirement is both reports (Cash Basis and Accrual Basis ) , same like indian Edition of Zoho Books showing. CASH BASIS RETURN is our BasicTips & Tricks Series - #4 Customize your manual PDF before export
Hello everyone! We’re back again with our Tips & Tricks series. Today, we’ll look at how you can customize your manual PDF before exporting it. With Zoho Learn, you can personalize the exported PDF with options such as headers, footers, colors, and customDigital Marketing Agency: Transforming Your Brand's Online Presence
Imagine trying to build a house on your own without the necessary tools or expertise—it’s overwhelming, right? Digital marketing is the same.Introducing Zoho Key Service, a simpler way to access LLMs without API keys
Available in the Professional, Enterprise, and Ultimate editions in the US, IN, AU, JP, and CA DCs. Hello everyone, We are excited to bring Zoho Key Service (ZKS) in Zoho CRM, a simpler way for organizations to access and use third party LLMs. You canReach us through our official support channels
Dear Customers, Thanks a lot for choosing Zoho! Our applications are built to help achieve your day-to-day business goals. We are committed to engaging with you, to understand and develop solutions that enhance your productivity. We are happy and readyI cannot add user to my account
I have an account, I deleted a user from the account and I have one unused licence which lasts for 23 days, I tried adding a new user and it said This user is not allowed to add in Zoho. Please contact support-as@zohocorp.com for further details, pleaseDomain Activation Issue
I purchased a domain through Zoho, and as I understand it, you were supposed to send me a domain activation link. However, I never received it. As a result, I was unable to activate the domain, and it is now suspended. Because of this, I am not receivingGrouping by Stage *type* in widgets
Hi Can I ask for a new feature? I'd like to be able to group by stage type in a Deal widget. That is by whether the Deal is in an Open Stage, a Closed Won Stage, or a Lost stage. Currently I can group by Stage, but if we have 10 open stages and one ClosedPlease release domain bravovietnam.com from an old account
Hello Zoho Support, I am trying to set up Zoho Mail with my domain bravovietnam.com on my account office@bravovietnam.com. Every time I add the domain, I get: "This domain is already associated with this account" — pointing to a DIFFERENT, older accountChatGPT Plugin / MCP Server auth error
Hi all I'm trying to connect the ChatGPT plugin for Zoho CRM but after username stage of the auth process, I get this error from the URL https://mcp.zoho.eu/mcp-client/ {"error_description":"Invalid request url, Request is not as per defined in oauthCreator -Dynamic addition of Customer Portal User Licenses
Hi, We have a Creator App for B2C about to get released. We are experiencing the Portal User license challenge. Unable to predict the number of users who will download and Subscribe. When a User is about Subscribe and the portal licenses does not exists,Need Multiple currency for Suppliers and Buyers
Hello, We need multiple currency support for buyer and suppliers, We are doing international business and we often sell goods in foreign currency as well as local currency, However zoho does not support this, I am trying Free agent and xero they support all currencies for suppliers Bills & expenses as well as buyers invoices, Kindly work on this feature will be great help to decide using zoho books Thank youEnhanced Zoho CRM and Office 365 calendar synchronization features!
Dear customers, We're excited to share some significant improvements to our Office 365 calendar synchronization features, aimed at providing you with more control and a more personalized experience. What’s new Choose your Office 365 calendar: During theZoho Books Support
Dear Team, Zoho Books offers a demo before you purchase zoho books. But after that when he actually purchases the product he has to rely on toll free number or help documents. But this might get frustrated in the initial period. Specially in initial period.How to add a fee based on payment method
I currently accept both ACH payments and credit card. I want to add a 3% fee to a number of my subscription plans if the customer chooses to use a credit card (and not ACH/checking). How do I do this? Is there an in-built feature, or would i have to createWhat's New in Zoho Invoice | July – September 2026
Hello everyone! We're back with the latest updates and enhancements we've rolled out in Zoho Invoice from July to September 2026. Here's what's new this quarter: Zoho Invoice is Now Available in Nigeria Introducing the Super Admin Privilege E-InvoicingZohoBooks - "Account transactions" report doesn't have any "Desciptions"
Hi, I'd like to push for this to be included in ZohoBooks: In a "account transactions" report all the numbers are right, but I'd really like to see the "Description" as part of this report, i.e. the line-item-description as I would see it in the bank statement. Essentially all you see is a list of numbers adding up to the total. It is very difficult to see if things are right without being able to see what exactly each transaction refers to. Going into each transaction one-by-one is not a workableAddress limits per customer by edition
I’m on the Standard edition and have reached a limit of 30 addresses under a single customer. Before I move to an annual Professional subscription, I need to confirm the following: What is the maximum number of addresses allowed under one contact, andExport from List view
I'm constantly having the issue where my users are building lists in ListView for various objects and then realising they cant export the data, then they have to go and build the data set in reports to export. I would like to see the ability to export to excel/csv from ListView.Cannot apply tags to multiple items at once
It is very frustrating needing to apply tags to notes individually. Even worse that it takes multiple clicks to do it. Can there please be an update to: 1.) Allow us to apply tags to batches of notes in one go. 2.) Make it less clicks to add a tag 3.)Get all hiring updates via Zoho Cliq bot notifications
We’re introducing a new way to stay updated on recruitment activities: Cliq Bot notifications. Now you can receive Zoho Recruit notifications directly in Zoho Cliq—alongside your existing in-app alerts and emails. Whether it’s a candidate status change,Notes Acknowledgement
It would be great to have emojis that can be used for Notes. Emojis such as Thumbs Up to let someone know you agree with them or a emoji for thanks. It's a simple way to acknowledge that you read someone's note. Moderation update: Emoji reactions forIs it possible to log text messages from iphone into Zoho CRM
My team is more and more utilizing text messaging to communicate with clients. Does Zoho have a solution for logging these text messages when clicking "Send Text Message" from the Zoho app. Much like when you call, you get prompted to log a call, canProject Finances: Fully Accessible within Projects
Project finances and work items are now on the same screen and it transforms the way you run your project. Managing your project finances is now much easier and in the same screen as your work items. Access quotes, invoices, bills, sales orders, and purchaseUI / UX Improvements
Please consider changing the Dependency Details window from a column-based layout to a list-based layout, or allowing users to choose their preferred layout. The current column-based view uses screen space inefficiently and makes navigation difficult,Next Page