Understand Zoho CRM’s Deal Prediction Mechanism and how to use the Link/Unlink Deal Email APIs compa

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. 



      • 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

        • Service disruption in Zoho Cliq (EU Region) – February 9, 2026

          Hello everyone, We’d like to inform you about a brief service disruption that affected Zoho Cliq users in the EU region earlier today. The issue has been resolved, and all services are now operating normally. Summary On February 9, 2026, Zoho Cliq experienced

        • Spotlight series #26 - Build slides with visual clarity using Diagram

          Hello all! The feature in the spotlight this month is Diagram. Let's say you are a part of a project kickoff meeting and your teammate starts explaining the project life cycle like this: "First we ideate, then we create an initial prototype and share

        • Client scripts for Zoho Books ?

          Good day everyone, I am looking for a way to be able to interact with the Quotes and Invoices as they are being created. Think of it like Zoho client script in Zoho CRM. But for the life of me I dont see a way to do this. The issue with having function

        • Uplifted homepage experience

          Editions: All editions. Release Note: Available in CA and SA DCs (Standard, Professional). Hello everyone, Creating your homepage is now much easier, more visual, and more impactful. Until now, your homepage allowed you to display custom views, widgets,

        • Unable to produce monthly P&L reports for previous years

          My company just migrated to Books this year. We have 5+ years financial data and need to generate a monthly P&L for 2019 and a monthly P&L YTD for 2020. The latter is easy, but I'm VERY surprised to learn that default reports in Zoho Books cannot create

        • Crossbeam

          Does anyone use Crossbeam with their Zoho CRM? I'm looking for a way to import Crossbeam partner leads into Zoho CRM. If so: - What's your experience been like? - Are you able to automatically import Crossbeam leads > Zoho CRM? How? - What doesn't work

        • Access forms within a form

          I have multiple forms that I would like to create access to for users within one form. Example: I have forms A, B, C, D. I would like to create a form with the links to forms A, B, C, & D. That way we can send one link and then the user can select the

        • WorkDrive issues with Windows Explorer Not Responding

          We are using WorkDrive to collaborate on editing video content. We have a lot of files and quite a few are a few gigs. Recently anytime I try and work with the files Explorer freezes for a couple minutes whether it's dragging the files into Premiere or

        • Issues with Actions By Zoho Flow

          Hi, I have a workflow that fires when a deal reaches a stage. This then sends out a contract for the client to sign. I have connected this up through Actions by Zoho Flow. Unfortunately this fails to send out. I have tracked it down to the date fields.

        • Fill Mail Merge document up with subform fields of an Inventory module record being in the Related List

          Hi, I try to insert subform fields from an inventory module record being on the Related List of another inventory module record into a Mail Merge template without success. For example: we use ratecards in licensing and this ratecard items are available

        • Enhancements for Currencies in Zoho CRM: Automatic exchange rate updates, options to update record exchange rates, and more

          The multi-currency feature helps you track currencies region-wise. This can apply to Sales, CTC, or any other currency-related data. You can record amounts in a customer’s local currency, while the CRM automatically converts them to your home currency

        • 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

        • How can we add products using a Wizard?

          We want to create a Wizard to add products. Why is there no possibility to use the products module when creating a wizard?

        • Orphan email alias blocking user creation – backend cleanup required

          Hello Zoho Mail Support, I´m unable to assign or create the address xx@iezzimatica.ar in my organization. Current situation: Alias cannot be assigned to any user (system says it is already in use) New user with this address cannot be created Address does

        • Direct Access and Better Search for Zoho Quartz Recordings

          Hi Zoho Team, We would like to request a few enhancements to improve how Zoho Quartz recordings are accessed and managed after being submitted to Zoho Support. Current Limitation: After submitting a Quartz recording, the related Zoho Support ticket displays

        • Ensure Consistent Service Delivery with Comprehensive Job Sheets

          We are elated to announce that one of the most requested features is now live: Job Sheets. They are customizable, reusable forms that serve as a checklist for the services that technicians need to carry out and as a tool for data collection. While on

        • Something wrong with client script??

          Someone have the same feeling? Client script behavior become very strange..

        • API 500 Error

          Hello amazing ZOHO Projects Community, I get this message. How can we solve this? { "error": { "status_code": "500", "method": "GET", "instance": "/api/v3/portal/2010147XXXX/projects/2679160000003XXXX/timesheet", "title": "INTERNAL_SERVER_ERROR", "error_type":

        • Polish signer experience to compete with docusign

          I would like to suggest that someone spend the little bit of time to polish the signer experience, and the email templates to more of a modern professional feel. They are currently very early 2000s and with some simple changes could vastly improve the

        • how to change the page signers see after signing a document in zoho sign

          Hello, How can I please change the page a signer sees after signing a document in Zoho Sign? I cannot seem to find it. As it is now, it shows a default landing page "return to Zoho Sign Home". Thanks!

        • Digest Janvier - Un résumé de ce qui s'est passé le mois dernier sur Community

          Bonjour chers utilisateurs, Le premier mois de l’année est déjà derrière nous ! Découvrons ensemble comment s'est passé janvier pour Zoho Community France. Nous avons démarré le mois avec une nouvelle intégration entre Zoho Desk et Zoho Contracts. Cette

        • contact support

          I have 2 request for a phone call and not received one call as promise!

        • Can we fetch Deal owner and Deal owner email with COQL?

          While fetching deal deatils with coql api and while fetching deal owner name and email it is just giving owner id not ginving name and email https://www.zohoapis.in/crm/v2/coql

        • Zoho Social - Cliq Integration / Bot

          Dear community / zoho, I am looking for a way to create a bot within Zoho Cliq to update my colleagues about our Zoho Social activities. For example, if a new post is published, it would be great if this post automatically would be shared in our social

        • Comment to DM Automation

          Comment to DM automation feature in Zoho Marketing Automation, similar to what tools like ManyChat offer. Use case: When a user comments on a social media post (Instagram / Facebook), the system should automatically: Send a private DM to the user Capture

        • Send / Send & Close keyboard shortcuts

          Hello! My team is so close to using Zoho Desk with just the keyboard. Keyboard shortcuts really help us to be more efficient -- saving a second or two over thousands of tickets adds up quickly. It seems like the keyboard shortcuts in Desk are only for

        • Handling Agent Transfer from Marketing Automation Journey to SalesIQ WhatsApp

          We are currently using Marketing Automation for WhatsApp marketing, and the features are great so far We have a scenario where, during a campaign or journey, we give customers an option to chat with our sales team. For this, we are using SalesIQ WhatsApp

        • Webinar - Getting Started with Zoho LandingPage

          Want to launch landing pages that support real marketing goals? This webinar is designed to help you understand the role landing pages play in your overall campaigns and how they contribute to lead generation and conversions. During this session, you’ll

        • Increase Round Robin Scheduler Frequency in Zoho Desk

          Dear Zoho Desk Team, We hope this message finds you well. We would like to request an enhancement to the Round Robin Scheduler in Zoho Desk to better address ticket assignment efficiency. Current Behavior At present, the Round Robin Scheduler operates

        • Zoho mail to contacts and leads, but not to accounts?

          We use the accounts tab a lot for our business because they can be linked to the sales orders. Now we want to use the mail add on to link communication of our emails to our accounts. However this is only possible for contacts and leads? It would be convenient

        • Python - code studio

          Hi, I see the code studio is "coming soon". We have some files that will require some more complex transformation, is this feature far off? It appears to have been released in Zoho Analytics already

        • Marketing Tip #19: Upsell on product page to increase order value

          Upselling doesn’t have to feel pushy. It can actually feel helpful when done right. Think "people also bought", upgrades, add-ons, or complementary items. A smart upsell increases your average order value and improves the customer experience by making

        • CRM limit reached: only 2 subforms can be created

          we recently stumbled upon a limit of 2 subforms per module. while we found a workaround on this occasion, only 2 subforms can be quite limiting in an enterprise setting. @Anonymous User I've read about imminent increase of other components (e.

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

        • オンライン勉強会のお知らせ Zoho ワークアウト （2/19 参加無料）

          ユーザーの皆さま、こんにちは。コミュニティチームの中野です。 2月開催のZoho ワークアウトについてお知らせします。 今回はZoomにて、オンライン開催します。 ▶︎参加登録はこちら（無料） https://us02web.zoom.us/meeting/register/6AyVUxp6QDmMQiDGXGkxPA ━━━━━━━━━━━━━━━━━━━━━━━━ Zoho ワークアウトとは？ Zoho ユーザー同士で交流しながら、サービスに関する疑問や不明点の解消を目指すイベント「Zoho

        • Removing Tables from HTML Inventory Templates - headers, footers and page number tags only?

          I'm a bit confused by the update that is coming to HTML Inventory Templates https://help.zoho.com/portal/en/kb/crm-nextgen/customize-crm-account/customizing-templates/articles/nextgen-update-your-html-inventory-templates-for-pdf-generator-upgrade It says

        • Ability to Link Reported Issues from Zoho Desk to Specific Tasks or Subtasks in Zoho Projects

          Hi Zoho Desk Team, Hope you're doing well. When reporting a bug from Zoho Desk to Zoho Projects, we’ve noticed that it’s currently not possible to select an existing task or subtask to associate the issue with. However, when working directly inside Zoho

        • How do i move multiple tickets to a different department?

          Hello, i have several tickets that have been assigned to the wrong department.  I am talking about hundreds of automatically generated ones that come from a separate system. How can i select them all at once to move them to another department in one go? I can select them in "unsassigned open tickets view" but i can't find a "move to another department" option. I also can't seem to assign multiple tickets to the same agent in that same view. Could somebody advice?

        • Let us view and export the full price books data from CRM

          I quote out of CRM, some of my clients have specialised pricing for specific products - therefore we use Price Books to manage these special prices. I can only see the breakdown of the products listed in the price book and the specialised pricing for

        • Set Default Status of Assembly to "Assembled" When Entered in UI

          I've just discovered the new "confirmed" status of Assemblies within Inventory. While I understand the intent of this (allowing for manufacturing planning and raw material stock allocation), it was initially confusing to me when manually entering some

        • Next Page