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:

1. If the contact has only one open deal, the email is linked to that deal.
2. If the contact has multiple open deals, the email is linked to the most recently modified deal, provided the deal is not closed-lost.
3. 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:

1. Correct an incorrect association.
2. Attach an email to a deal that the prediction could not infer.

Zoho CRM provides two focused APIs for this:

1. Link Deal to Emails API.
2. Unlink Deal from Emails API.

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

1. owner (JSON object, mandatory): Specify the details of the user whose email you want to link. It consists of the following keys
1. name:  Specify the name of the user whose email you want to link.
2. id: Specify the ID of the user whose email you want to link.
2. 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]  
3. 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
1. module(JSON object, mandatory): Specify the details of the Deals module. It consists of the following keys
1. api_name: Specify the API name of the Deals module.
2. id: Specify the ID of the Deals module.
2. 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.
3. id: Specify the ID of the Deals record that the email must be linked to.
   

Notes 

1. An email can be linked to only one deal at a time.
2. You can link multiple emails in a single request by providing multiple Emails objects in the request body.
3. 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

1. owner_ID Specify the unique ID of a user whose email you want to unlink. 
2. 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

1. Prediction linked an email to deal A.
2. Your business logic determines that the email belongs to deal B.
3. Call the Unlink API.
4. Call the Link API with the correct deal.

Key behavior

1. Unlinking does not delete the email.
2. Email remains visible under the Contact.
3. 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.

1. Use Associate Email API when you want to log a new email into CRM and associate it to a record.
2. 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.

1. Deal Prediction handles the common association scenarios.
2. Link and Unlink APIs provide manual control over Email-Deal associations.
3. 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

• Topic Participants

• Mable Mary M P

  

• Sticky Posts

• Kaizen #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

• Kaizen #222 - Client Script Support for Notes Related List

  Hello everyone! Welcome to another week of Kaizen. The final Kaizen post of the year 2025 is here! With the new Client Script support for the Notes Related List, you can validate, enrich, and manage notes across modules. In this post, we’ll explore how

• Kaizen #217 - Actions APIs : Tasks

  Welcome to another week of Kaizen! In last week's post we discussed Email Notifications APIs which act as the link between your Workflow automations and you. We have discussed how Zylker Cloud Services uses Email Notifications API in their custom dashboard.

• Kaizen #216 - Actions APIs : Email Notifications

  Welcome to another week of Kaizen! For the last three weeks, we have been discussing Zylker's workflows. We successfully updated a dormant workflow, built a new one from the ground up and more. But our work is not finished—these automated processes are

• Recent Topics

• Zoho Mail iOS app update: Access Delegated Mailbox.

  Hello everyone! You can now access the delegated mailbox from within the iOS version of the Zoho Mail app. To access the delegated mailbox: Open the Zoho Mail app. Go on to the 'Email' module. Tap the profile picture. Choose the delegated mailbox Please

• How to convert Lead's country field from Text to Pick List

  Hi, I would like to change the default country field in ZCRM from text to pick list. It looks like not I can't delete default country field and recreate it as pick list nor can i create an new custom field country because such a label belong to default field. So what do I have to do? Any ideas? L

• How create a draft via workflow?

  I wish to create a workflow rule for specific emails that creates a draft response - not an automatic email reply, but just a draft with a set response ready to be verified by an agent who can then manually select recipients. Alternatively, the workflow

• Function #51: Transaction Level Profitability for Quotes

  Hello everyone, and welcome back to our series! In a previous post, we shared a custom function that could determine the profitability of a Sales Order. Today, we are presenting a similar function that calculates the profitability of a Quote. The setup

• New feature: Invite additional guests for your bookings

  Hello everyone, Greetings from Zoho Bookings! We are happy to announce the much-awaited feature Guest Invite, which enhances your booking experience like never before. This feature allows additional participants to be invited for the bookings to make

• Improved Contact Sync flow in Google Integration with Zoho CRM

  Hello Everyone, Your contact sync in Google integration just got revamped! We have redesigned the sync process to give users more control over what data flows into Google and ensure that this data flows effortlessly between Zoho CRM and Google. With this

• الخصم على مستوى فاتورة المبيعات

  السلام عليكم ورحمة الله وبركاته مطلوب في إنشاء خصم على مستوى فاتورة المبيعات وليس على مستوى البند أريد معرفة الطريقة؟

• VAT and Taxes option not available

  Dear ZOHO Team , The VAT and Taxes options in my ZOHO books account not available,I tried to find how to enable or check the way to use this option but unfortunately couldn't find it anywhere ,I'm in UAE ,kindly let me know what to do to solve this issue

• Default Tagging on API-generated Transactions

  If one assigns tags to an Item or Customer, those tags get auto-populated in each line item of an Invoice or Sales Order when one creates those documents. However, if one creates the Sales Order or Invoice via the API (either directly coding or using

• Direct Feed (Bank)

  Is Direct feed integration for AlRajhi and ADCB bank supported by Zoho Books in GCC/Saudi

• Sales Order, Invoice and Payment numbers

  Hi zoho friends, it is me again, the slow learner. I'm wondering if there is a way to have it so the Sales order, invoice and payment numbers are all the same? It would be easier for me if they were the same number so there is not so many reference numbers

• Customer Satisfaction (CSAT) Report

  From data to decisions: A deep dive into ticketing system reports The customer satisfaction (CSAT) report helps teams understand how customers feel about their support experience, identify service gaps, and continuously improve the help desk. It turns

• Timeline Tracking Support for records updates via module import and bulk write api

  Note: This update is currently available in Early Access and will soon be rolled out across all data centers (DCs) and for all editions of Zoho CRM. The update will be available to all users within your organization, regardless of their profiles or roles.

• Shifts in Zoho People vs Zoho Shifts?

  Hello Zoho People Team, We hope you are doing well. We are evaluating the Shifts functionality within Zoho People and comparing it to the standalone Zoho Shifts product. We’ve encountered comments and discussions suggesting that the Shifts feature inside

• Disable fields in During action in Blueprint?

  Hi there. I've tried field disable (setReadOnly(true)) using client script and the event is onMandatoryFormLoad on detail page, assuming it'll work on blueprint fields, but it bears no result. Is this the expected behaviour? That we can't do this yet?

• Develop and publish a Zoho Recruit extension on the marketplace

  Hi, I'd like to develop a new extension for Zoho Recruit. I've started to use Zoho Developers creating a Zoho CRM extension. But when I try to create a new extension here https://sigma.zoho.com/workspace/testtesttestest/apps/new I d'ont see the option of Zoho Recruit (only CRM, Desk, Projects...). I do see extensions for Zoho Recruit in the marketplace. How would I go about to create one if the option is not available in sigma ? Cheers, Rémi.

• Subforms and automation

  If a user updates a field how do we create an automation etc. We have a field for returned parts and i want to get an email when that field is ticked. How please as Zoho tells me no automation on subforms. The Reason- Why having waited for ever for FSM

• Allow Managers to Create Shifts for Their Departments in Zoho People

  Hello Zoho People Product Team, Greetings and hope you are doing well. This feature request is related to Zoho People - please don't move it to zoho one! We would like to submit a feature request regarding shift management permissions in Zoho People.

• Zoho Learn and Zoho CRM integration

  I would like to see an integration between Zoho Learn and Zoho CRM. 1. To be able to add articles in a related list in all modules 2. Zia to suggest related articles in a Deal or Case or Lead 3. Ability to read / search articles during a call / follow

• Maintain steady traffic to your domain: How Domain Aliasing helps

  Consider this scenario: An organization has its primary domain as administrator.com. Now it wants to shorten its domain to admin.com because it's simpler and easier to remember. However, changing the domain completely can cause the following problems:

• Why Sharing Rules do Not support relative date comparison???

  I am creating a Sharing Rule and simply want to share where "Last Day of Coverage" (Date field) is Greater than TODAY (Starting Tomorrow). However, sharing rules don't have the option to compare a date field to a relative date (like today), only to Static

• Workflow rule only allows 10 workflow per module

  Apparently a Zoho professional edition only allows 10 workflow rules per module. This makes workflow allocation literally impossible while allocating potential to different members of the team. I have 15 licenses. Is there a way in which related alerts can be varied? In other words, is it possible to have different related alerts be triggered with different rule criteria. so if I say, if potential is 'x' then trigger related alert 'x' and if potential is 'y' then trigger related alert 'y' Thanks,

• IF Statement in Zoho CRM Formula Field

  Hi, I am attempting to write a formula field that will give me one result if one statement AND another statement are true, then a different value if the first statement AND a different statement are true, else 0. Stated differently: if account = destination

• CRM Percent custom fields: When will it show the % symbol and behave like %?

  1. Actually Percent custom fields fail to show the % symbol. 2. When in formulas Percent fields work like number: 100 x 5% = 5 ideal world 100 x 5% = 500 what happens actually 3. When importing Percent fields the % symbol has to be removed and the data

• Editing the Ticket Properties column

  This is going to sound like a dumb question, but I cannot figure out how to configure/edit the sections (and their fields) in this column: For example, we have a custom "Resolution" field, which parked itself in the "Ticket Information" section of this

• "Total Hours" on Employee Attendance Report

  I'm learning that in Zoho jargon, "total hours" does not include paid breaks. Or at least not the way that my setup is working. That seems a little weird to me, since most jurisdictions in the US don't differentiate between time spent on paid break and

• Fixed assets in Zoho One?

  Hi, We use Zoho Books and have the fixed asset option in it. I started a trial for Zoho One and I do not see that as an option. Is the books that is part of zoho one equivalent to Zoho Books Elite subscription or is it a lesser version? Thanks, Matt

• Integration with...

  Dear Zoho Commerce team, Please could you consider the integration within Zoho Commerce / Inventory and Qapla'? (https://www.qapla.it/en/) This app is better than Aftership in many ways: - Aftership integration require PRO plan and price start from more

• Generate leads from instagram

  hello i have question. If connect instagram using zoho social, it is possible to get lead from instagram? example if someone send me direct message or comment on my post and then they generate to lead

• Adding Markdown text using Zoho Desk API into the Knowledge Base

  Hi Zoho Community members, We currently maintain the documentation of out company in its website. This documentation is written in markdown text format and we would like to add it in Zoho Knowledge Base. Do you know if there is REST API functionality

• Create case via email

  Good Afternoon, I have just registered and am taking a look around the system. Is it possible to create a case via email.  I.e. an employee/client/supplier emails a certain address and that auto generates the case which then prompts a member of staff

• Need a Universal Search Option in Zohobooks

  Hello Zoho, Need a Universal Search Option in Zohobooks to search across all transactions in our books of accounts. Please do the needful Thanks

• Locked Notebook

  Hi, I hadn't used my Notebook in some time and was refamiliarizing myself with it. I clicked a lock icon and now I can't unlock. When I hit the information or unlock icons I'm taken to a page with the notebook icon and a keyboard. When I type, nothing

• Hide fields only for creation

  Hello, I'd like to hide some fields only during the creation of a contact in Zoho CRM. In fact I have some fields that are automatically calculated thanks to an automation, so when my users create a contact I don't want them to fill those fields. I know

• Issues with Zoho Sheet in Mac

  I have downloaded the Zoho App from App Store but It is failing to Save As, Open & Download Operations. App Store

• Weekly Sales Summary

  Is it possible to generate a weekly report in Zoho Books to show -$$ amount of estimates generated -# of estimates generated by Salesperson -$$ amount of Sales Orders created -$$ amount of Invoices generated

• OpenAPI Specs are just plain wrong

  The provided yml files for generating the OpenAPI specs are absolutely riddled with errors and inconsistencies. From missing fields on the objects, to just incorrectly named resource objects. I'm having to go through and manually changing the spec to

• Add Account column to Invoice screen

  Please show the account column on Invoice creation screen. It is an unnecessary step to have to click add additional info and then select the account for line item. Example : on the bill creation screen when entering description we can easily code it against an account. On the invoice screen it requires additional click. Adding the column on the Invoice screen will make it faster to enter transactions. We currently have 5-6 different accounts that we code line items against, You can imagine the extra

• Custom Footer – Zoho Writer Document

  Hello everyone, I’m having an issue adding a custom footer in a Zoho Writer document. I would like to insert my company information (including a logo + address) in the footer. The problem is that when I add these elements, the main content of my pages

• Report grouping

  I have added a grouping in a report but it is not working how i had expected. I wanted to group a summary on a field named Size but when i add the grouping the report is still showing me each record and making a summary at the bottom of the report. What

• Next Page