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

• Formatting Problem | Export to Zoho Sheet View

  When I export data to Zoho Sheet View, ID columns are automatically formatted as scientific notation. Reformatting them to text changes the actual ID values. For example, 6557000335603071 becomes 6557000335603070. I have attached screenshots showing this

• Introducing Workqueue: your all-in-one view to manage daily work

  Hello all, We’re excited to introduce a major productivity boost to your CRM experience: Workqueue, a dynamic, all-in-one workspace that brings every important sales activity, approval, and follow-up right to your fingertips. What is Workqueue? Sales

• Feature Request - The Ability to Link A Customer with a Vendor

  Hi Finance Suite Team, Many businesses buy and sell products from the same companies or individuals. For example, a car sales business may buy a car from a member of the public, and that member of the public may also buy a new car from us. This makes

• Long table name (sync from Zoho Creator)

  Dears, How can I remove the suffix in parentheses? These tables are synced from Zoho Creator and are treated as system tables, so their names cannot be changed. This issue makes the aggregation formulas look awful.

• [Free Webinar] Learning Table Series - Streamlining incident management process with Zoho Creator

  Hello everyone, We’re excited to invite you to another edition of the Learning Table Series webinar. As you may already know, we've moved to a purpose-based approach in the Learning Table Series this year. Each session now focuses on how a Zoho Creator

• Unattended - Silent

  How can I hide the tray icon / pop up window during unattended remote access for silent unattended remote access?

• Importing into Multiselect Picklist

  Hi, We just completed a trade show and one of the bits of information we collect is tool style. The application supplied by the show set this up as individual questions. For example, if the customer used Thick Turret and Trumpf style but not Thin Turret,

• Text snippet

  There is a nice feature in Zoho Desk called Text Snippet. It allows you to insert a bit of text anywhere in a reply that you are typing. That would be nice to have that option in Zoho CRM as well when we compose an email. Moderation Update: We agree that

• Marketing Tip #18: Make your online store mobile-friendly to improve traffic

  Most online shoppers browse on their phones first. If your store is hard to read, slow to load, or tricky to navigate on mobile, they’ll bounce fast. A mobile-friendly store doesn’t just look nice; it improves engagement, reduces drop-offs, and helps

• [Need help] Form closed. Please contact your form administrator for further assistance.

  https://forms.zohopublic.com/cceinfoifly1/form/CCE2025CCEFocusGroupRegistrationForm2025Fall/formperma/s_8XcLETTbFxZ_TAS4r_W6W5UBl8o5oxEnIX35IBKg4 I checked we didn't exceed the usage limit and form availability is enabled, Please help us enable this form

• Zoho People. Updating TabularData

  I am trying to update tabular data in the record. I always have the same response. I have checked many times. Section ID is correct. May be something wrong with request structure itself. Can someone help me. Body content type: form urlencoded query params

• Automatically CC an address using Zoho CRM Email Templates

  Hi all - have searched but can't see a definitive answer. We have built multiple email templates in CRM. Every time we send this we want it to CC a particular address (the same address for every email sent) so that it populates the reply back into our

• Unable to Send Different Email Templates for Different Documents in Zoho Sign

  Hello Zoho Community, I am facing a limitation with Zoho Sign regarding email notifications sent to customers when a document is sent for signing. Currently, whenever I send any template/document for signing, the email notification that goes to the customer

• Reminder needs 0 minute choice

  I most use 0 minute reminders.  Every other calender service has this choice.  If I create an event in my Android calendar with 0 minute reminder it will change to 5 minute.  Please ad 0 as a reminder choice, this should be a 5 minute fix.  Thanks.

• Customer ticket creation via Microsoft Teams

  Hi all, I'm looking to see if someone could point me in the right direction. I'd love to make it so my customers/ end users can make tickets, see responses and respond within microsoft teams. As Admin and an Agent i've installed the zoho assist app within

• Is there a way to update all the start and end dates of tasks of a project after a calendar change?

  Hi! Here's my situation. I've built a complete project planning. All its tasks have start dates and due dates. After completing the planning, I've realized that the project calendar was not the right one. So I changed the project calendar. I now have

• How to update task start date when project start date changes?

  Hi there, When the start date of a project changes, it's important to update the start dates of the tasks associated with that project to reflect the new timeline. Is there a way to shift the start date of all project tasks when the start date of a project

• Issue with Picklist Dropdown Not Opening on Mobile

  Hello I am experiencing an issue with picklist values on mobile. While the arrow is visible, the dropdown to scroll through the available values often does not open. This issue occurs sporadically, it has worked occasionally, but it is very rare and quite

• using the client script based on the look up filed i wnat to fetch the record details like service number , service rate

  based on selected service look up field iwant to fetch the service serial number in the serice form how i achive using client script also how i get the current date in the date field in the on load of the form

• Zoho Books/Square integration, using 2 Square 'locations' with new Books 'locations'?

  Hello! I saw some old threads about this but wasn't sure if there were any updates. Is there a way to integrate the Square locations feature with the Books locations feature? As in, transactions from separate Books locations go to separate Square locations

• Zoho Commerce - How To Change Blog Published Date and Author

  Hi Commerce Team, I'm discussing a project with a client who wants to move from Woo Commerce / Wordpress to Zoho Commerce. They have around 620 blog posts which will need to be migrated. I am now aware of the blog import feature and I have run some tests.

• Does zoho inventory need Enterprise or Premium subsrciption to make Widgets.

  We have Zoho One Enterprise and yet we can't create widgets on inventory.

• ZMA shows as already connected to Zoho CRM, but integration not working

  When I try to connect ZMA with Zoho CRM, it shows as already connected, but the integration doesn’t seem to be working. I’ve attached the screen recording for reference.

• Automatic Email Alerts for Errors in Zoho Creator Logs

  Hello, We would like to request a feature enhancement in Zoho Creator regarding error notifications. Currently, Zoho Creator allows users to view logs and errors for each application by navigating to Zoho Creator > Operations > Logs. However, there is

• Workflow Rule - Field Updates: Ability to use Placeholders

  It will be great if you can use placeholder tags to update fields. For example if we want to update a custom field with the client name we can use ${CONTACT.CONTACT_FIRSTNAME}${CONTACT.CONTACT_LASTNAME}, etc

• Password Assessment Reports for all users

  I'm the super admin and looking at the reporting available for Zoho Vault. I can see that there is a Password Assessment report available showing the passwords/weak and security score by user. However I'm confused at the 'report generated on' value. Monitor

• Can't change form's original name in URL

  Hi all, I have been duplicating + editing forms for jobs regarding the same department to maintain formatting + styling. The issue I've not run into is because I've duplicated it from an existing form, the URL doesn't seem to want to update with the new

• Setting certian items to be pickup only

  How do we have some items that are pickup only? I have several items in my item's list that I do not ship. But they need to be on the website to be sold, and picked up in store. Need to be able to do this as one of these products is a major seller for

• Using gift vouchers

  We would like to be able to offer a limited number of gift vouchers, of varying values, to our customers, and are looking for the best way to do this. We have looked at Coupons and Gift Certificates, but neither seem to fit the bill perfectly. Coupons:

• Automatically updating field(s) of lookup module

  I have a lookup field, which also pulls through the Status field from the linked record. When the lookup is first done, the Status is pulled through - this works perfectly. If that Status is later updated, the lookup field does not update as well. As

• Zoho Commerce and Third-party shipping (MachShip) API integration

  We are implementing a third-party shipping (MachShip) API integration for our Zoho Commerce store and have made significant progress. However, we need guidance on a specific technical challenge. Current Challenge: We need to get the customer input to

• Adding custom "lookup" fields in Zoho Customization

  How can I add a second “lookup” field in Zoho? I’m trying to create another lookup that pulls from my Contacts, but the option doesn’t appear in the module customization sidebar. In many cases, a single work order involves multiple contacts. Ideally,

• Can you import projects into Zoho Projects yet?

  I see some very old posts asking about importing project records into Zoho Projects. But I can't find anything up to date about the topic. Has this functionality been added? Importing tasks is helpful. But we do have a project where importing projects

• Zoho Inventory. Preventing Negative Stock in Sales Orders – Best Practices?

  Dear Zoho Inventory Community, We’re a small business using Zoho Inventory with a team of sales managers. Unfortunately, some employees occasionally overlook stock levels during order processing, leading to negative inventory issues. Is there a way to

• Automation #10 - Auto Assign Ticket based on Keywords

  This is a monthly series designed to help you get the best out of Desk. We take our cue from what's being discussed or asked about the most in our community. Then we find the right use cases that specifically highlight solutions, ideas and tips on optimizing

• Automate attendance tracking with Zoho Cliq Developer Platform

  I wish remote work were permanently mandated so we could join work calls from a movie theatre or even while skydiving! But wait, it's time to wake up! The alarm has snoozed twice, and your team has already logged on for the day. Keeping tabs on attendance

• Reusable Custom Functions Across Department Workflows

  Dear Zoho Desk Team, We appreciate the powerful workflow automation capabilities in Zoho Desk, particularly the ability to create and use custom functions within workflows. However, we have encountered a limitation that impacts efficiency and maintainability.

• Don't Allow Customer to Edit Values After Submitting Ticket

  After a customer submits a ticket through the customer portal, they can go into the ticket and see some of the values from the questions they answered in the sidebar. Currently, a customer can edit these values even after they submitted them. This makes no sense. We ask very specific questions that we don't want customers to later change! Please disable the ability for customers to edit the values to their submission questions in the portal. Screenshot attached.

• Analytics <-> Invoice Connection DELETED by Zoho

  Hi All, I am reaching out today because of a big issue we have at the moment with Zoho Analytics and Zoho Invoice. Our organization relies on Zoho Analytics for most of our reporting (operationnal teams). A few days ago we observed a sync issue with the

• text length in list report mobile/tablet

  Is there a way to make the full text of a text field appear in the list report on mobile and tablet? With custom layouts, the text is always truncated after a certain number of characters.

• Next Page