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

• Blueprint or Validation Rules for Invoices in Zoho Books

  Can I implement Blueprint or Validation Rules for Invoices in Zoho Books? Example, use case could be, Agent confirms from client that payment is done, but bank only syncs transactions tomorrow. in this case, Agent can update invoice status to done, and

• Resetting auto-number on new year

  Hi everyone! We have an auto-number with prefix "D{YYYY}-", it generates numbers like D2025-1, D2025-2, etc... How can we have it auto-reset at the beginning of the next year, so that it goes to D2026-1? Thanks!

• The Social Wall: December 2025

  Hello everyone! As we wrap up the final edition of the Social Wall for 2025, it’s the perfect time to look at what went live during December. QR code generator From paying for coffee to scanning metro tickets, QR codes are everywhere and have made everyday

• Custom AI solutions with QuickML for Zoho CRM

  Hello everyone, Earlier, we introduced Custom AI Solutions in CRM that let you access QuickML for your custom AI needs. Building on that foundation, we’ve now enabled a deeper integration: QuickML models can be seamlessly integrated into CRM, and surface

• Helper Functions and DRY principle

  Hello everyone, I believe Deluge should be able to use 'Helper functions' inside the main function. I know I can create different standalones, but this is not helpful and confusing. I don't want 10000 different standalones, and I dont want to have to

• Introducing workflow automation for the Products module

  Greetings, I hope all of you are doing well. We're happy to announce a few recent enhancements we've made to Bigin's Products module. The Products module in Bigin now supports Workflows, enabling you to automate routine actions. Along with this update,

• Zia Formula Expression Generator for Formula fields

  Hello everyone! Formula fields are super useful when you want your CRM to calculate things for you but writing the expression is where most people slow down. You know what you want, but you’re not fully sure which function to use, how the syntax should

• Issue with Zoho Creator Form Full-Screen View in CRM Related List Integration

  Hi Team, We have created a custom application in Zoho Creator and integrated it into Zoho CRM as a related list under the Vendor module, which we have renamed as Consignors. Within the Creator application, there is a form named “Pickup Request.” Inside

• Wrapping up 2025 on a high note: CRM Release Highlights of the year

  Dear Customers, 2025 was an eventful year for us at Zoho CRM. We’ve had releases of all sizes and impact, and we are excited to look back, break it down, and rediscover them with you! Before we rewind—we’d like to take a minute and sincerely thank you

• Restrict Users access to login into CRM?

  I’m wanting my employees to be able to utilize the Zoho CRM Lookup field within Zoho Forms. For them to use lookup field in Zoho Forms it is my understanding that they need to be licensed for Forms and the CRM. However, I don’t want them to be able to

• Unknown table or alias 'A1'

  I would like to create a subquery but i am getting the following error: Unknown table or alias 'A1' used in select query. This is the sql statement:  SELECT A1.active_paying_customers, A1.active_trial_customers, A1.new_paying_signup, date(A1.date_active_customers), 

• in the Zoho creator i have address field based the customer lookup im selecting the addresss , some times the customer address getting as null i want to show as blank

  in the Zoho creator i have address field based the customer lookup im selecting the addresss , some times the customer address getting as null ,i want to show as blank instead of showing null. input.Billing_Address.address_line_1 = ifNUll(input.Customers_Name.Address.address_line_1,"");

• Question about upgrade and storage space Zoho Notebook

  After upgarding my Zoho Notebook plan, I am running into the following issue. I just upgraded from a free Zoho Notebook subscription to Pro Lite after I got a notification in my Window Zoho Notebook desktop app saying that I had run out of space. However,

• Printing to a brother label maker

  I see allot of really old unanswered posts asking how to print to a label maker from a zoho creator app. Has their been any progress on providing the capability to create a customized height & width page or print template or whatever to print labels?

• Sync desktop folders instantly with WorkDrive TrueSync (Beta)

  Keeping your important files backed up and accessible has never been easier! With WorkDrive desktop app (TrueSync), you can now automatically sync specific desktop folders to WorkDrive Web, ensuring seamless, real-time updates across devices. Important:

• Track online, in-office, and client location meetings separately with the new meeting venue option

  Hello everyone! We’re excited to announce meeting enhancements in Zoho CRM that bring more clarity and structure to how meetings are categorized. You can now specify the meeting venue to clearly indicate whether a meeting is being held online, at the

• Announcing new features in Trident for Mac (1.32.0)

  Hello everyone! We’re excited to introduce the latest updates to Trident, which are designed to reinforce email security and protect your inbox from evolving threats. Let’s take a quick look at what’s new. Deliver quarantined emails. Organization admins

• Marketing Tip #5: Improve store speed with optimized images

  Slow-loading websites can turn visitors away. One of the biggest culprits? Large, uncompressed images. By optimizing your images, your store loads faster and creates a smoother shopping experience leading to higher sales. It also indirectly improves SEO.

• SMS to customers from within Bigin

  Hi All, Is there anyone else crying out for Bigin SMS capability to send an SMS to customers directly from the Bigin interface? We have inbuilt telephony already with call recordings which works well. What's lacking is the ability to send and receive

• Admins cannot see each others' Scheduled Reports?!

  Very frustrating that as an admin I cannot see what my reports my fellow admins have created and scheduled.  After asking about this on the help chat, I was told the issue is trust and security.  By giving someone Admin status, it means we trust them with those responsibilities. Please change this, it is not a good process to have to bother other users to change a report or change users within a report.

• Writer update results in BitDefender blocking it as malware

  After updating Writer to latest update, Bitdefender blocked the app and writer no longer runs.

• Missing Import Options

  Hello, do I miss something or is there no space import option inside of this application? In ClickUp, you can import from every common application. We don't want to go through every page and export them one by one. That wastes time. We want to centralize

• Zoho CRM Portal Field Level Permission Issue

  Hi Support Team, I am using the Zoho CRM Portal and configuring field-level editing permissions. However, we are unable to restrict portal users from editing certain fields. We have created a portal and provided View and Edit (Shared Only) access for

• Custom Fonts in Zoho CRM Template Builder

  Hi, I am currently creating a new template for our quotes using the Zoho CRM template builder. However, I noticed that there is no option to add custom fonts to the template builder. It would greatly enhance the flexibility and branding capabilities if

• Collaboration with customers made easy with Zoom Meeting and Zoho Desk integration

  Hello everyone! We are happy to announce that you can now integrate your Zoho Desk account with Zoom Meeting. The integration bridges the gap between digital communication and human connection, empowering teams to deliver timely support when it matters

• CRM Canvas - Upload Attachments

  I am in the process of changing my screens to Canvas.  On one screen, I have tabs with related lists, one of which is attachments.  There doesn't appear to be a way to upload documents though.  Am I missing something really obvious?  Does anyone have

• TrueSync regularly filling up my local disk

  Seems that WorkDrive's TrueSync randomly starts filling up my local hard drive space. None of the folders have been set as "Make Offline" but still it seems to randomly start making file offline. The settings of the app is so minimal and is of no real

• Kaizen #194 : Trigger Client Script via Custom buttons

  Hello everyone! Welcome back to another interesting and useful Kaizen post. We know that Client Scripts can be triggered with Canvas buttons and we discussed this with a use case in Kaizen#180. Today, let us discuss how to trigger Client Script when a

• Picklist field shows "none" as default

  Hello, Is there an option to avoid showing "none" as the default value in a picklist field? I also don't want to see any option displayed. My expectation is to have a blank bar, and then when I display the drop-down list, I can choose whichever I wa

• Stage-probability mapping feature in custom module

  Hi, I'm building a custom module for manage projects. I would like to implement the stage-probability feature that Potentials has. Is this possible?

• Field Description is very small

  Hello, The field Description in the activity is very small. Why don't try open a new window, or a bigger popup, or increase the width of the "popup". Example:

• StatusIQ

  Please add StatusIQ to data sources. We using site24x7 and StatusIQ together and site24x7 integration is already there. Thanks and regards, Torsten

• In Zoho People, the Operations buttons are frequently not visible or do not appear consistently.

  In Zoho People, the Operations buttons are frequently not visible or do not appear consistently. We request you to please investigate and address this issue, as it is affecting daily HR operations and user access.

• Marketing Tip #14: Increase cart value with product bundles

  Bundling products is a great way to increase average order value while giving customers more convenience. Think “camera + tripod + memory card” or “soap + lotion + bath salts.” Bundles make shopping easier and feel like a better deal. It’s a win-win for

• Problem with Workdrive folders

  I'm having a problem a problem accessing files in a Zoho work drive folder when using the Zoho writer app. The problem folder appears grayed out in the Zoho work drive window in both the online and writer application. However I can open the folder in

• Pre-orders at Zoho Commerce

  We plan to have regular producs that are avaliable for purchase now and we plan to have products that will be avaliable in 2-4 weeks. How we can take the pre-orders for these products? We need to take the money for the product now, but the delivery will

• Can multiple agents be assigned to one ticket on purpose?

  Is it possible to assign one ticket to two or more agents at a time? I would like the option to have multiple people working on one ticket so that the same ticket is viewable for those agents on their list of pending tickets. Is something like this currently

• Edit default "We are here to help you" text in chat SalesIQ widget

  Does anyone know how this text can be edited? I can't find it anywhere in settings. Thanks!

• Feature Request: Sync Leave Tracker to Zoho Mail / Calendar or provide option to download information

  Zoho Leave Tracker offers the option to sync the leave Calendar to Microsoft 365 and Google Calendar. Adding an option to sync to Zoho-Mail Calendar would avoid duplication and add significant value for users. An alternative would be to allow users to

• Compensation | Salary Packages - Hourly Wage Needed

  The US Bureau of Labor Statistics says 55.7% of all workers in the US are paid by the hour. I don't know how that compares to the rest of the world, but I would think that this alone would justify the need for having an hourly-based salary package option.

• Next Page