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

    • Announcing the new SKILL.md for Zoho CRM and the updated OAS repository!

      We are introducing a new zoho-crm skill to make working with Zoho CRM Developer tools (like APIs, functions, widgets, client scripts, queries etc) easier and faster, with the help of AI in your preferred AI harness like Claude Code, Codex, Cursor, VSCode

    • Kaizen #261 : Using Zoho CRM Skill to generate complex COQL queries

      Hello everyone, In the previous Kaizen posts, we introduced the zoho-crm SKILL.md and discussed how it can help you when you are working with Zoho CRM APIs and Client Script. In this Kaizen, we will focus on using the Zoho CRM `SKILL.md` with GitHub Copilot

    • Kaizen #256 - Build an Arrival Readiness Web Tab in Zoho CRM

      Hi everyone! Welcome back to the Kaizen series! In the post, we discuss a use case in hospitality industry: how an Arrival Readiness web tab widget can be used to let reception staff identify and resolve issues before arrival of guests. Use case In the

    • 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

      • Recent Topics

      • What are the best practices for managing tax records and financial information for a small business?

        I’m interested in learning how other small business owners and accounting professionals organize their financial records and prepare for tax filing. With bookkeeping, expense tracking, income records, and tax documents all needing to stay accurate, having

      • How to Open Google Takeout and Thunderbird MBOX Files?

        MBOX files are used by email clients and services, such as Google Takeout and Mozilla Thunderbird, to store email messages. It can, however, be difficult to open such files if you don't have an email programme that is compatible. Google Takeout enables

      • Convert MBOX to PDF Free on Mac and Windows

        MBOX files are widely used for storing email messages in email clients such as Thunderbird, Apple Mail, and other programs that support the MBOX format. Although this format is useful for handling emails, it can at times be inconvenient to access the

      • How to Convert Apple Mac Mail to PST for Outlook for Free?

        Apple Mail is a widely used email program among Mac users, but what do you do if you want to transfer your emails to Microsoft Outlook? In such a situation—for example, when you are moving from a Mac to a Windows computer or when you need to use Outlook

      • Cannot apply tags to multiple items at once

        It is very frustrating needing to apply tags to notes individually. Even worse that it takes multiple clicks to do it. Can there please be an update to: 1.) Allow us to apply tags to batches of notes in one go. 2.) Make it less clicks to add a tag 3.)

      • Automating CRM backup storage?

        Hi there, We've recently set up automatic backups for our Zoho CRM account. We were hoping that the backup functionality would not require any manual work on our end, but it seems that we are always required to download the backups ourselves, store them,

      • not able to convert pdf to jpg and other forms and vice versa.

        i want to change my pdf to jpg, word, etc and some times jpg to pdf. i don't know how to do in this.

      • Changing an existing item to different accounts & inventory-tracked

        Hi everyone, I have an item in Zoho Books that was originally set up as a non-inventory item. Over time, I associated it with different sales and purchase accounts, and I now have many invoices, bills, and reports that use this item. My business process

      • Address limits per customer by edition

        I’m on the Standard edition and have reached a limit of 30 addresses under a single customer. Before I move to an annual Professional subscription, I need to confirm the following: What is the maximum number of addresses allowed under one contact, and

      • How to Convert Emails to PDF Format in Batch

        It is helpful to convert emails into PDF format when you want to save important messages, when you need to share business correspondence, or when you wish to keep email records for future reference. PDF files can be readily opened, printed, and shared

      • Months of WooCommerce–Zoho Inventory sync failures and repeated support requests – has anyone experienced this?

        Months of WooCommerce–Zoho Inventory sync failures and repeated support requests – has anyone experienced this? I run a small retail business using WooCommerce and Zoho One. For months, I have been trying to resolve recurring synchronisation failures

      • Function #24: Automatically display deal name from Zoho CRM on quotes in Zoho Books

        Deals allow businesses to organize and visualize their sales pipeline. This provides a clear overview of all potential opportunities and helps in making informed decisions. Zoho CRM empowers you to create deals or potentials for your clients and monitor

      • Lookups and Custom Modules

        I created a Custom Module that I'm calling "Item Purchasing Group". This module will store information for groups of Items that must be purchased together (including minimum overall quantities and/or values, etc.). This will have a one-to-many relationship

      • Zoho Books | Product updates | October 2026

        Hello users, October brings a range of new features and enhancements to Zoho Books, designed to simplify compliance, streamline accounting workflows, and improve inventory management. From the launch of the Nigeria Edition and France’s e-invoicing capabilities

      • Create custom rollup summary fields in Zoho CRM

        Hello everyone, In Zoho CRM, rollup summary fields have been essential tools for summarizing data across related records and enabling users to gain quick insights without having to jump across modules. Previously, only predefined summary functions were

      • Button or Links order

        Is there a way to re-order the buttons or links that are created? Moderation Update: With our recent enhancement to custom button creation from the layout editor, administrators can now reorder custom buttons directly from the layout editor, and this

      • Zoho Books | Product updates | August 2026

        Hello users, July has been an exciting month for Zoho Books! This month, we're excited to introduce HTML PDF Templates, Placeholders as Pills, expanded approval workflows for Sales Returns and Journals, and significant compliance updates across the India,

      • Bulk updating tags

        My organisation handles a number of restricted funds. We previously did this by having a chart of accounts where each restricted fund has its own income and expense accounts. However, our accountant changed this, moving all transactions into accounts

      • Download or Backup Bulk Emails from IMAP Server

        Taking email messages from an IMAP server and saving them is a wise method for ensuring that important emails are kept safe and easy to access. No matter whether you have a business email address or a personal mailbox, keeping a local copy of your emails

      • Zoho Writer Label Template Merge/Print Via API/Webhook/Flow

        Short version of goal: To be able to kick off a Zoho Writer Label Template Document via API or Webhook or even using Zoho Flow. As of right now I have been unable to figure out a way to do that. Long version of goal: We would like to press a button (run

      • Kaizen #263: Using Zoho CRM Skill to Build Widgets

        Hello everyone! Welcome back to another exciting Kaizen post. In the previous Kaizen posts, we introduced the zoho-crm skill.md and explored how it can help with Zoho CRM APIs, Client Scripts, complex COQL queries, and Skill to build Queries. In this

      • Zoho notebook No login

        Hello Team, I recently downloaded and installed the latest version of zoho notebook for windows. But I am not able to login without providing any sso or email address. Did you removed the no login feature for this app? This is just a windows app. can

      • Search is completely broken for PC

        I go to note, try to search for "mtga" and it shows 702 results (it's a big note), highlights all letters "m" and I can't find anything. Same for "gathering" - it thinkgs I think only for "g". Looking for "zoho" shows as if I searched only for "z". Using

      • Losing description after merging tickets

        Hello, We merge tickets when they are about the same topic from the same client. It happens sometimes. We recently noticed that after the merger only the description from the master ticket is left in a thread. And the slave-ticket description is erased.

      • Behind a great customer experience is a team

        Hi everyone, October is here, and the first week marks the Customer service week. Each year, we thank our customer service professionals. Service professionals are all around us, even in our own workplaces: They handle essential administrative work like

      • What's New - August and September 2026 | Zoho Backstage

        Hello everyone, August and September bring a fresh wave of intelligence to Zoho Backstage. AI takes the spotlight with tools that help you create content, support attendees, and manage how AI fits into your events. Alongside AI, we’ve refined email communication,

      • Images Not Displaying Properly in Zoho Desk

        Hi, We are experiencing an issue with image rendering in Zoho Desk, affecting both incoming and outgoing emails. Images embedded in email conversations are not displaying properly. Instead, we see broken image icons or empty placeholders where the images

      • Announcing the new SKILL.md for Zoho CRM and the updated OAS repository!

        We are introducing a new zoho-crm skill to make working with Zoho CRM Developer tools (like APIs, functions, widgets, client scripts, queries etc) easier and faster, with the help of AI in your preferred AI harness like Claude Code, Codex, Cursor, VSCode

      • Widget Height were destroyed

        All widget heights in the Details Canvas view are broken. Moderation Update: This is a known issue with widget heights in Client Script popups and flyouts. A fix is in progress, and this post will be updated once it's released.

      • Zoho Projects - Has something changed regarding to linking Projects and Deals via the API?

        I am trying to link Zoho Projects to Deals in CRM using the API, but each time, the Deal Contact is added as a Client user and receives an email invite asking them to join the organisation. These are internal projects and the customer should not have

      • How long does it take to review campaigns?

        Hello Zoho, i scheduled my campaigns yesterday afternoon and it has been under review for over how many hours and those campaigns were supposed to be out yesterday so new ones can go out today. Is there something i'm doing wrong?

      • Convert MSG to PDF in Bulk with Attachment Free

        Microsoft Outlook saves each email as an MSG file, keeping with it key information like the sender, the recipient, the subject, the date, the body of the message, and any attachments. It can, however, be quite difficult to access a large number of MSG

      • Using Mail Merge Template to Print Documents with One Subform Record's Fields per Document

        Hello, We have a Mail Merge template created in Zoho Writer which is not able to perform the functionality which is currently required to automate the documentation task portion of our process. The CRM module we are primarily using is based on a "Loans"

      • Convert MBOX to PST File Using Free Methods

        MBOX is a mailbox format that is used by various email clients and services, such as Thunderbird, Apple Mail, Eudora, and Google Takeout. Yet, in order to be able to open your MBOX emails in Microsoft Outlook, you have to convert them from MBOX to PST

      • Zoho Community Digest - September 2026 | Part 4

        Hi everyone, and welcome back! The final week of September brought a revamped Books integration in Zoho CRM and Zoho Key Service for LLM access without API keys, Zoho Creator's audit trail becoming a full enterprise-grade auditing system, and Zoho One

      • Automate weekly reports from Channels | Zoho Cliq AI use case #01

        Scrolling endlessly through numerous threads in a Cliq channel and manually counting how many have been closed, how long people took to reply, and who actually participated can be tedious. After 20 minutes, you might have a number that no one can verify.

      • Apple Mail to Outlook Converter - Export Apple Mac Mail to PST File

        Apple Mail is a well-known email application among people who use Macs, whereas Microsoft Outlook is widely employed for both personal and business use. Should you decide to move from Apple Mail to Outlook, you'll probably need to transfer your mailbox

      • Creator -Dynamic addition of Customer Portal User Licenses

        Hi, We have a Creator App for B2C about to get released. We are experiencing the Portal User license challenge. Unable to predict the number of users who will download and Subscribe. When a User is about Subscribe and the portal licenses does not exists,

      • Zoho Tables is now part of Zoho One!

        Hey everyone! We've got some exciting news to share. Zoho Tables is now included in your Zoho One subscription at no extra cost. If you're already on Zoho One, head to your app list, add Zoho Tables, and get started right away. You don't need a separate

      • How to import PST files in Office 365?

        You can import PST files into Office 365 using native Outlook applications, the Microsoft Purview network upload method, or specialized third-party migration tools. Choosing the right method depends on whether you are migrating a single mailbox or executing

      • Next Page