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

• Social Media Simplified with Zoho Social: Preview your Instagram grid before posting

  For a platform like Instagram that relies on visual appeal, it's important that you plan your image and video content in a way that holds your audience's attention. Planning your grid ahead of time gives you the benefit of understanding how your posts

• Error code 1000

  Can you please tell me why the following, occasionally causes this error via the api, not every time ?... zoho.books.updateRecord("salesorders",organizationID,salesorderID,{"template_id":"#################069","custom_fields":[{"label":"DelDate","value":"Tuesday,

• VAT rates - exempt and out of scope

  Good Evening, UK based company here. I am a bit confused in respect of setting up VAT rates for exempt goods and services; at present I am simply leaving the VAT rate blank in the transactions in order to prevent any VAT appearing in the VAT return. When

• How to loop through Multiple Upload and Display Actual File Name

  I have been reading the help on the File Upload Control and reviewed the Deluge help on files and I can not figure out how to loop through the uploaded files and do anything but get the automatically created file names. The code below will run but each

• abou arattai

  I want to use the Arattai app for business purposes, so please convert my account to a business account.I have my own invoice app, and I want to link it with the Arattai app for direct messaging.

• Configurable Zoho Cliq Notifications for Zoho People Alerts

  Hello Zoho People Product Team, Greetings and hope you are doing well. We would like to request an enhancement to Zoho People notifications, enabling a native delivery via Zoho Cliq with admin-level control, similar to the notification settings available

• Looking back at Zoho Calendar in 2025

  Hello Zoho Calendar Community, As we step into a brand-new year, we’d like to take a moment to thank you for being an active and valued part of the Zoho Calendar community. Your trust, feedback, and continued engagement motivate us to keep evolving and

• There was an error while connecting to GSTN

  I am trying to file GSTR1. Everything flows smoothly until I reach the final step of filing the return. After I enter the PAN and OTP for filing it raises the error "There was an error while connecting to GSTN"

• Zoho Books Extension: What Happens If Custom Fields Already Exist?

  When developing Zoho Books extensions, what happens if the target Zoho Books organization already has a custom field with the same API name as one defined in the extension? I’m asking because we originally created an on-Books version of this functionality,

• Internal Server Error (500) When Attempting to View Banking Transactions

  I am experiencing an Internal Server Error (500) when attempting to view transactions across all of my banking accounts. Despite multiple attempts to resolve this, I have received little more than runaround from support, and the issue remains unresolved.

• How do I add a blank line to the Organisation Address Format?

  I'd like to have my VAT number, for example, shown prominently by having a clear gap between it and the address block above, but any blank lines in the address format get ignored in PDF outputs.

• Automatic Invoice Number generation for createRecord

  Hello, while testing some custom Buttons in my Zoho Books application, I noticed that I get an error that previously did not occur. After some further digging I found that the automatic transaction numbering of invoices no longer work in my organization.

• Adding number of days to an estimate.

  I need both QTY of item and "number of days hire" in my estimates at the line item level. Any clues as to how this is done would be greatly appreciated. It needs to calculate. Thanks J

• Books Api: listing expenses created after certain dates

  Is there any parameter I can add to the List Expenses endpoint that will let me look up expenses by when they were created?

• Why can't we change the Account type from an Expense to an Asset?

  Like the question. Why in QuickBooks for example if I mistakenly created an account as an expenses and I already captured information in those accounts, I can just change the account type from expense to asset

• Is it possible to do validation for the Actions added to Reports?

  We have an all-around On Validate function that checks all the possibilities before the Created/Edited form submissions. We want to have a button in the report view, so we can change records without entering. We are able to add this button, and it does

• Ability to Edit Ticket Subject when Splitting a Ticket

  Often someone will make an additional or new request within an existing ticket that requires we split the ticket. The annoying part is that the new ticket maintains the subject of the original ticket after the split so when the new ticket email notification

• [Free Webinar] Environments in Zoho Creator - Creator Tech Connect

  Hello Everyone, We’re delighted to kick off the 2026 edition of the Zoho Creator Tech Connect Series and are excited to continue this learning journey with you. The Creator Tech Connect series is a free monthly webinar featuring deep-dive technical sessions

• Zoho Voice API SMS

  I made a post request in Zapier to try to send an SMS. Authentication appears to be configured correctly. I followed the documentation and I'm getting a 400 Error "Internal Server Error". Not helpful at all. Anyways, I could not find any information on

• How do I change (error) display messages

  Hi! I would like to edit display messages like "invalid entries" and "enter a value for Nome" and so on into Italian language messages. How can I do that? Already tried on Validate on form submit. Where I am failing? Thanks in advance.

• Record Overseas Transactions Along with CC charges

  Hi All, We receive payments via stripe in multiple currencies and stripe takes around 2.5% fees. The amount is settled in INR into our local bank. What should be the currency of the income account used for Stripe payments? Here is a sample flow that we

• Easier onboarding for new users with stage descriptions

  Greetings, I hope all of you are doing well. We're happy to announce a recent enhancement we've made to Bigin. You can now add descriptions to the stages in your pipeline. Previously, when creating a pipeline, you could only add stages. With this update,

• Pieds de page personnalisé - Document Zoho Writer

  Bonjour à tous, Je rencontre un souci avec l’ajout d’un pied de page personnalisé dans un document Zoho Writer. Je souhaite insérer les informations de mon entreprise (notamment un logo + adresse) dans le pied de page. Le problème, c’est que lorsque j’ajoute

• Credit card transactions are backwards after importing statements

  I am new to Zoho Books so I'm importing my firm's bank and credit card statements in. My credit card statements have a single column with negative numbers so that is the option I chose. But when I went to categorize the credit card transactions, I can

• Permissions on Views

  Having the option of any agent creating custom views is firing back and got a situation where there are a hundred different views across the team and tickets are not being dealt in the most efficient of ways. Tickets seems to be missed by some agents,

• Function #8: Add additional charges to invoices

  Here goes one of the highly sought-after custom functions in Zoho Books. If you find yourself needing to apply additional charges to customers on their invoices (say credit card surcharges, or fuel charges applicable to customers from a certain region,

• VIsual maindmaps in Zoho notebook Ai

  Can I create and export VIsual maindmaps in Zoho notebook Ai

• 1stDibs Integration to Zoho Inventory

  Hello is it possible to integrate my Zoho inventory and 1stDibs?

• Community Question: Renewal vs Invoicing

  This is a question for the community. Does anyone else consider there to be a difference between a subscription renewal event and sending out a recurring invoice for a subscription? For example, let's say customer XYZ purchases a 1-year subscription to

• cloud console support for music websites

  Hi Friends, I am not from a very technical background.. So need support from the Zoho family. I want to build a e-commerce website which is in Musical Niche. It will help people learn music & play instruments of all types. There are a few players in the market like Chordify , Guitaa, Guitar Dashboard, ChordU & few others. But I all these websites allow only a few instruments  to play. So I want to build a better  website than the one I mentioned. So wnated to know what UI & AI should I use so that

• Scheduled Reports - Do not send empty report

  Hello, We are intensively using reports in the CRM, especially for sales managers. When data is empty, they still receive an email. Can you add an option to avoid sending the report when data is empty?

• Is Zoho One Desktop more secure than Zoho One Web SaaS?

  Is Zoho One Desktop more secure than using Zoho One in browser? Inherently, it seems desktop would be unless you don't do things like share your pw or leave pc on. I am concerned about data being on the cloud or someone else's server and database.

• Reminder Settings - Time Tracker

  On the time tracker in Reminder Settings I created a reminder according to the Zoho manual. But a manager asked me to change the message that goes in the email. Is it possible to change the message? I didn't find that in the Zoho manual. Another question: I configured to receive the reminder everyone who logged in less than 40 hours. Does Zoho consider less than 40 hours of the current week or the whole month? Another situation, I put it so that I and another specific user would receive the notification,

• Create Item group from a composite Item

  I have applied my mind for hours but cannot figure this out. Can you have a composite item in an item group?. E.g. We bundle different color and size SKU's together as composite items. Also Using composite items as Bill of Materials. We want to create

• Main difference of Zoho Recruit Corporte version and Staffing HR vesion

  Hi Zoho, I need help to fully understand what is the main key point differences of Recruit Corporate version versus the Staffing HR version? We are currently using Corporate HR version and we are looking on having an insightful automated reporting, does

• Out of Stock items showing in Commerce

  I have over 6000 items and most are not in stock, but all items are showing up in Commerce whether they are inventory or not. What option or feature can you use to hide items in Commerce at zero or negative quantities? I currently am using Commerce for

• Is it possible to transfer data from one related list to another within the same module ?

  In the Leads module, there is an existing default Product related list that already contains data. Recently, I added a custom multi-lookup field, which created a new related list in the same Leads module. Now, I need to move the existing data from the

• How to implement new online payment gateway?

  Hello, Can you tell me how to proceed to implement my local payment gateway? DIBS has an open avaiable API that should be easy to implement into ZOHO BOOKS. http://tech.dibspayment.com/dibs_payment_window

• Formula working in MS Excel , is not working in Zoho Sheets, Filter fuction which is working in MS sheets per the attached workbook / Daily update.

  Filter function , which is working in MS Excel is not working in Zoho sheets. Please help on function of filter of particular class sheets and extract students name who has more than 3.5 hours of study hours on particular day depending on date in D7 cell.

• New in Smart Prompt: Record Assistant for contextual assistance, and support for new AI models

  Smart Prompt helps teams stay informed and move faster by providing relevant suggestions where work happens in CRM. With this update, Smart Prompt becomes more adaptable to your organization’s AI preferences. You can now choose which Large Language Model

• Next Page