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

• Showing the map along with mileage expense

  When you use the GPS to track mileage, it shows you the map of the actual path travelled. It would be very useful and practical to save that map with the mileage expense, so that when the report is created, it provides a map of each mileage expense associated

• ID:2406331

  Hello, I have sent the form (ID:2406331) but no answer after two days. This is a paid subscription, I am not allowed to use the eighth paid slot of 50GB email space anymore, only 7 are being used. Is anyone going to help me please so I can use the eighth

• CRM x WorkDrive: File storage for new CRM signups is now powered by WorkDrive

  Availability Editions: All DCs: All Release plan: Released for new signups in all DCs. It will be enabled for existing users in a phased manner in the upcoming months. Help documentation: Documents in Zoho CRM Manage folders in Documents tab Manage files

• Approval Workflow for Purchase Orders Abrir

  The requirement is , that all purchase orders greater than or equal to 5000 go through an approval process from certain people, but within books I only see that the approvers can be by levels or any approver but we cannot enter a rule like these. Can

• I would like to know wich person viewed the file

  I have a franchise and my Operative Manual is in WorkdriveI, the user can´t download but despite I know How many views the file had, I would like to know wich person viewed the file Is it possible? thank you

• Transaction Rule Matching

  Q1. Is there a method to have the Transaction Rules applied across multiple Bank Accounts? Q2. To match "contains" text in Transaction Rules, is a wildcard or regular expression required? Is it case sensitive? Would searching for "issue" in the following

• Zoho Desk - Event Calendar View

  Hi Desk team, Are there any plans to introduce a calendar or timeline view for Events in Zoho Desk? It would be very helpful if we could see Events visually in a calendar and/or timeline. This is very helpful when desk side support activities need to

• Notebook on Mac: Fuzzy fonts in list view

  Hi, I am running Notebook on Mac OS 26. Generally it works fine, and the font display in the notes themselves is crisp. However, in the notes list (left of the open note) the font of the note titles as well as first lines is noticeable fuzzy. Attached

• Trigger workflows from SLA escalations in Zoho Desk?

  Hey everyone, I’m currently working with SLA escalation rules in Zoho Desk and ran into a limitation that I’m hoping someone here has solved more elegantly. As far as I can tell, SLA escalations only support fairly limited actions (like changing the ticket

• Zoho CRM Email Templates 100% Width No Background How?

  Hi, On the Zoho CRM Email Templates in setup > customization > templates > new templates > I choose blank template, but still it puts in a gray background and a max width for the email. I just want to make an email that looks like an email I would send from gmail that has no background or max width. How do you do this? 

• ZOHO CRM Quote Export / Quote Report

  How can I either Export my quote list, or create a Report that shows all quotes AND includes the NOTES field in a column. I attempted to Run a Report which includes ALL FIELDS, however it does not include the Notes Field (but oddly does include the fields

• Introducing Radio Buttons and Numeric Range Sliders in Zoho CRM

  Release update: 1. 2 March 2026: Currently out for CN, JP, AU and CA DCs (Free and standard editions). For other DCs, this will be released by mid-March. 2. 26 March 2026: CA, SA, AU, JP, CN DCs - Free, Standard, Professional, Enterprise, Ultimate, CRM

• All 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. 24

• Re-Apply SLA When Ticket Reopened from Closed Status?

  If you have an SLA applied, timers are deactivated when going to "On Hold" status type and reactivated when going back to an Open status type. What we discovered is when a customer replies to a closed case and it reopens, the SLA is not applied and timers

• Option to Delete Chats in IM

  Currently, there is no option to delete any chats in IM, regardless of their source.

• Adding a Mark Up

  Can you use the discount column to be a mar up column on estimates and invoices?

• URGENT. Recovering email without eArchive

  Hello, I have deleted some email from my trash but do not have eArchive. Is it possible to recovery without this? many thanks!

• Subscription Statuses - Dunning

  How are other companies handling the scenario when customers don't pay and dunning takes over? Our issue is that in my situations, we want our customers to be able to catch up their late payments and continue their subscription after the dunning process

• Logo Doesnt appear on email

  Hi, 1. PROBLEM: mails sent to customer from zoho invoice ( Estimates and incoices etc.) Logo doesnt appaer on email. 2. SUGGESTION: there must be an option to select from google fonts if we want specific font to the pdf templates. thanks

• How to see Statement Details Shown in Unclassified Transactions in All Transactions?

  All, The list of Unclassified Transactions show the Statement Details and Descriptions. What is the method to see that column in the All Transactions list? -Thanks!

• Non-Avalara Tax Automation wtih Zoho Books

  We are paying a ridiculous amount for Avalara. Our team wants to make a change, but they're the only software fully integrated with Zoho. We also don't have the bandwidth to do this manually, so we do need some sort of automated software solution. We

• Migrating to the new outgoing webhook model in Zoho Connect

  Dear User, Outgoing webhooks configured across the Zoho Connect Integrations page, Zoho Flow, and Zapier will stop working after May 31, 2026. This is due to an upcoming upgrade to our outgoing webhook flow. This update is mandatory only for networks

• Create formula calculations in Assemblies for scaling quantities

  Something we have been encountering with our composite items is dealing with scaling of quantity of one or more items within the composite assembly relative to the number of complete units being sold. I.e. running the equation 2(n-1) on one of the assembly

• Lastest update

  The latest update to notepad has completely trashed all my notes. If I go to view it it just opens up a screen with a box with dotted lines around it for me to add something I can import saved nodes but you can't view them at all. Anybody else having

• Is it possible to make tags "required"

  We would like to be able to make the tag field a requirement for agents before they can close a ticket. This would help with monthly reporting, where a lot of tickets end up with no tag, causing manual work to go back and add the correct tag for each

• Tip #67- Exploring technician console: Disable Input Devices- 'Insider Insights'

  Hello Zoho Assist Community! Picture this: you are in the middle of a critical remote session, carefully configuring a system or running an important update, and the customer accidentally clicks somewhere or types something that undoes your progress.

• What matters more in Zoho implementations: tools or system architecture?

  I recently worked on a full-stack migration for a catering equipment business using Zoho One with Shopify, and it raised a few interesting observations. The setup included migrating a large product catalog (around 9,700+ SKUs), integrating multiple supplier

• Facturation électronique 2026 - obligation dès le 1er septembre 2026

  Bonjour, Je me permets de réagir à divers posts publiés ici et là concernant le projet de E-Invoicing, dans le cadre de la facturation électronique prévue très prochainement. Dans le cadre du passage à la facturation électronique pour les entreprises,

• [Webinar] Solving business challenges: One tool for documents, forms, PDFs, e-signatures, and more

  Hi Zoho Writer users, Most businesses rely on multiple tools, such as a word processor, form builder, e-signature provider, and PDF editor, for their document workflows. Managing multiple subscriptions, switching between tools, and moving data across

• Deposit on invoice

  I'm trying to figure out how to customize an Estimate to include a Deposit/Retainer Invoice line within the Estimate. I tried creating my own custom field called "Deposit" where I manually inputted the deposit amount, which was nice. However, my employer

• Zoho NOTEBOOK: What are file size restrictions?

  I understand that Zoho NOTEBOOK is a free product, and what it offers is great. But I'm wondering what the file size restrictions are. When I record an audio note in Zoho Notebook, what is the maximum length of recording time/audio file size? When I wish to upload MP4 video, what is the maximum video size I can upload per Zoho Notebook restriction? Moreover, does Zoho Notebook use its own storage structure, or can I upgrade my storage for Zoho Notebook to add larger file attachments, videos and audio

• Concern Regarding Stock Validation in Inventory Management

  Hi Zoho Team, We would like to highlight a concern regarding stock validation in the inventory system. As per standard inventory management practices, if the stock level is zero, the system should not allow users to create a shipment, packing slip, or

• Automation Series #2: SLA vs Supervisor Rule in Zoho Desk

  SLA vs Supervisor Rule: Keeping tickets on track in Zoho Desk This post is part of the "Desk Automation Series," Chapter 1. Through this series, we will help you choose the right automation type in Zoho Desk by comparing commonly confused automations

• Zoho Recruit - Email Relay

  Good day, Has anyone succeeded in setting up an email relay for Office 365? If I add the details from https://support.microsoft.com/en-us/office/pop-imap-and-smtp-settings-8361e398-8af4-4e97-b147-6c6c4ac95353, I get the connection error. Regards, Eka

• Better use of contacts

  Zoho inventory has the ability to add multiple contacts to customers. However Zoho inventory doesn't currently provide a way to link a contact to objects like sales orders. This means that while you can tell what company has placed a sales order you can't

• Notebook AI limits

  Hi folks, Working with the AI transcription tools in Notebook, on the Mac App, which I find quite handy, but the one thing I am struggling with is the inability to either edit or copy the results of the transcript: I can't click in any of the boxes, and

• Disappointment with Zoho Payments

  Dear Gowdhaman, I am writing to inform you that I am removing Zoho Payments from my website. I cannot continue to disappoint my customers due to the lack of UPI support, as has been the case with my experience so far. Please note that the 0.5% transaction

• Zoho Commerce B2B

  Hello, I have signed up for a Zoho Commerce B2B product demo but it's not clear to me how the B2B experience would look for my customers, in a couple of ways. 1) Some of my customers are on terms and some pay upfront with credit card. How do I hide/show

• Exporting All Custom Functions in ZohoCRM

  Hello, All I've been looking for a way to keep about 30 functions that I have written in Zoho CRM updated in my own repository to use elsewhere in other instances. A github integration would be great, but a way to export all custom functions or any way

• Rename system-defined labels in Zoho CRM

  Renaming system-defined labels is now available across all DCs. Hello everyone, Zoho CRM includes predefined system fields across modules to support essential CRM operations. Until now, the labels of these fields were fixed and could not be edited from

• Next Page