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

    • inventory removal at packing list or shipment.

      currently our system is set to remove inventory at invoice. This is creating an inventory nightmare? Is it possible to change the settings to remove the item from inventory at either the packing slip stage or shipping the item.

    • Item description is not displayed

      I added the item description while importing the new item through the bulk item Excel sheet, and the import was completed successfully. However, I cannot see the description in the item details under Inventory. Could anyone please advise how to make the

    • Shared inbox unable to see replies

      Hi we are a small company me and someone else, we have a shared inbox for our sale@ and contact@ however we have this issue where by if i reply to an email or the other person reply to the email, it does not show it to them and therefore we end up replying

    • Record Payment - Auto Populate Amount as payments are selected

      When recording payments you have the option of clicking on "Pay in Full" next to the bill which automatically adds the total at the bottom of the page next to "Amount used for payments" but this should also auto populate / update the total at the top

    • Can't set conditional layout rule on lookup field in Zoho CRM

      Namaskaram Zoho CRM team, Usually any fields of module except mandatory fields can be hide using conditional layout rules. But that can't be set on lookup fields event that is not a mandatory fields. Many users are in need of that. Crafted with ❤️ Zoho

    • [Request] Pivot filter date option : from set date to relative value ie from 01Jan to LastMonth

      I don't think I can currently do this... but it's worth asking if it's possible. My use case is concerning annual leave which is calculated from the beginning of the calendar year (01Jan) then each month I want to have details of leave taken etc... In

    • Need to be able to apply layout rules to 'Multi Pick List'

      Currently, we are unable to apply layout rules to fields that are 'Multi Pick List'. This means we have to instead use checkbox fields, but they are inefficient. For example, we use the Multi Pick List to list our products. However, we're unable to apply

    • 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

    • My "trigger" panel disappear from my workflow ...

      Hello, I want to add a trigger to an email sequence, but the "trigger" panel has disappeared when I want to modify ...I used a predefined template to create this sequence, is that because of that? Thank you. I have attached a screenshot to you

    • Workflow Automation Not Triggering

      My Zoho CRM workflow sometimes doesn’t trigger when a record is updated, even though the workflow criteria appear to be met. What should I check to find out why the workflow is being skipped?

    • How can I add a Custom Field (or Customer_name) to a picklist?

      Our workflow is Shopify-->SO -->Picklist-->Package-->Shipment. We would like to have the Picklist template to include a custom field "Customer_Notes" (we have created this field already). This way we get alerted when a customer has notes on their account.

    • AI Calling

      Hi, does anyone have experience or any thoughts on AI Calling. Getting AI to make calls on behalf of your company. We are looking into it, but are finding it difficult to get info and providers that can assist.

    • Zoho Sheet as KB Document

      It would be nice if Zia Agents could take Zoho Sheets as part of the knowledge base. The use case here is that it's infinitely easier for humans to maintain a spreadsheet table than any .md / TAML / JSON document. For situations where humans are responsible

    • Ask the Experts: Five-hour live Q&A session with Zoho WorkDrive product experts

      Have questions about WorkDrive 5.0? Let’s talk! We recently launched Zoho WorkDrive 5.0, packed with powerful updates to help your team work smarter, stay secure, and get more value from your business content. From content-centric workflows and AI-powered

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

    • Zoho Community Digest - September 2026 | Part 3

      Hi everyone, and welcome back! Zoho CRM launches PRM for partner management, Bigin builds this year's Apple AI updates into the app, and Snapchat is now a connected channel in Zoho Social. There are also three notices worth reading, including WhatsApp

    • Change from OST to PST on Windows 10/11 Using Free Method

      There is an advantage in converting OST files to PST format if you need to access your Outlook data on a different computer, want to keep a local copy, or are trying to recover items from an old Outlook profile. The good point is that users of Windows

    • ERROR: This user is not allowed to add in Zoho. Please contact support-as@zohocorp.com for further details

      I can add new user for mail, i received message error about; This user is not allowed to add in Zoho. Please contact support-as@zohocorp.com for further details Try creating user name; instagram@eficaztecnologia.com.br

    • Support for Custom Fonts in Zoho Recruit Career Site and Candidate Portal

      Dear Zoho Recruit Team, I hope you're doing well. We would like to request the ability to use custom fonts in the Zoho Recruit Career Site and Candidate Portal. Currently only the default fonts (Roboto, Lato, and Montserrat) are available. While these

    • Ability to filter services and parts based on a field in the Work Order

      Hell FSM team, We have a customer with 2 value streams using Zoho FSM. Each value stream uses different products, at different price point. Currently, all of the products are accessible when creating a work order and modifying a service appointment, which

    • SubTotaks for Item Headers in Estimates

      Hi, Apparently, one can add Item Headers in Estimates in Zoho Books. Is this feature like an Estimate section with a SubTotals for each Item Header/Section? Or is the Item Header just a Title and cannot be SubTotalized? Thank You

    • Sync of products and orders between Zoho Inventory, Zoho Books and Shopify

      Good Day I migrated from QuickBooks to Zoho Books and Zoho Inventory at the beginning of this year. The migration team assisted with importing my data, but I am currently experiencing multiple issues affecting syncing between Shopify and Zoho. 1. SKU

    • Best practices for importing phone numbers

      I've recently found a problem with my phone provider, integrated with Zoho CRM, where a phone number that starts with 00 instead of + won't work. The problem has no solution: they tell me to replace all 00 with + I've always preferred using 00 instead

    • Copy + Paste in Notes: Text color and text background are not retained

      I've recently started using Zoho Notebook as an Evernote replacement. When copying and pasting text within Zoho Notes, I notice that the formatting of the text (text color and background color) is not retained when pasting. Only the attributes "Bold"

    • Add Comprehensive Accessibility Features to Zoho Writer

      Hello Zoho Writer Team, We hope you are doing well. We would like to submit a feature request to enhance Zoho Writer with a full set of accessibility tools, similar to the accessibility options already available in the Zoho Desk agent interface. 🚧 Current

    • MAKING ENTRY TIME MORE USER FRIENDLY AND FASTER O PREVENT TAB TIME

      I AM CURIOUS TO KNOW IF WE CAN MAKE IT MORE USER FRIENDLY WHILE MAKING BILLS , I MAJORLY USE OVER DESKTOP SO I AM SUGGESTING TO REMOVE TAB TIME WHILE ENTERING BILL OR MAKING INVOICE DIRECT JUMP TO ONLY REGULAR PARTS OF THE BILL . YOURS RAKESH 782866

    • Email Forwarding to Zoho Desk Failing After Migration from Gmail to Outlook (Microsoft)

      We recently migrated from Gmail to Microsoft Outlook. Since the migration date, emails sent by our customers are no longer being received by Zoho Desk. I tried setting up the email forwarding rules in Outlook similar to what we had in Gmail, but it still

    • Shopify B2B Integration: Option to Match Customers by Company Name

      It would be great if the Shopify integration could include Company Name as a customer matching option. At the moment customers can only be matched by: Email Name Email and Name Phone For businesses using Shopify B2B, the company is often the customer

    • How does Zoho handle the daylight savings time change in Alberta?

      Alberta has just made the decision to get rid of daylight savings. This means that as of November 1, 2026 we remain on UTC-6 year-round. We have timing errors in meetings scheduled after that For example, we scheduled meetings in late November at 9:00

    • Free Methods to Convert PST to MBOX on Mac & Windows

      Converting PST files to MBOX is often needed when moving Outlook mailbox data to email clients such as Thunderbird, Apple Mail, or other MBOX-supported applications. The process can be different on Windows and macOS, and free methods may involve several

    • Zoho Payroll: Product Updates - Q3, FY2026

      Over the past quarter, Zoho Payroll has added several updates to make payroll easier to process, configure, and manage. The most notable improvements cover bank integrations, reimbursement support, payslip enhancements, employee exit documentation, payroll

    • Print checks for owner's draw

      Hi.  Can I use Zoho check printing for draws to Owner's Equity?  This may be a specific case of the missing Pay expenses via Check feature.  If it's not available, are there plans to add this feature?

    • Deliver exceptional customer experience with Field Service Management in Zoho Service Plus

      The advent of automation and personalization in the AI era has raised customer expectations exponentially for faster resolution of issues with less tolerance to friction in the process. Fast, accurate, and intelligent service that understands customer

    • Zoho Extensions 101: Building extensions for Zoho People

      Hello developers! Welcome to our new video series on building extensions for Zoho People! If you're new to extension development or looking for guidance on building extensions for Zoho People, you're in the right place. We've curated a series of videos

    • Build A Happier Workforce With Zoho People

      The success of an organization depends on its people. Therefore, a comprehensive and cloud-based HRMS software is an integral part of the IT ecosystem for the business. With a wide number of key modules to define the structure of an organization, manage

    • 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

    • Project Change Orders and Additions

      We are in the process of migrating from QuickBooks Online to Zoho Books. We have Zoho One and like the ability to sync all of our data across everything. And I like that projects work in a way that's less dumb than QuickBooks. I'm trying to figure out

    • Support Recording Payments in a Different Currency Than the Invoice Currency

      We would like to request the implementation of a feature that allows users to record customer payments in a currency different from the currency of the original invoice. Current Limitation in Zoho Books Currently, if an invoice is issued in USD, Zoho

    • Customer Statement Showing Incorrect Negative Balance Due to Unused Advance

      Dear Zoho Support Team, We are facing an issue with the Customer Statement in Zoho Invoice related to customer advances/mobilization advances. The issue is that when a customer has made an advance payment that has not yet been fully utilized against invoices,

    • 【10/15・残席わずか】Zoho Championに学ぶ！Zoho Campaigns メール配信の基礎・活用勉強会

      皆さま、こんにちは。ゾーホージャパンの中野です。 10月15日（木）、Zoho コミュニティ初となる「Zoho Campaigns メール配信の基礎・活用勉強会」をオンラインで開催します！ 今回の登壇者は、Zoho の導入・活用支援に豊富な経験を持つZoho Champion の岡安 裕一さんです。 「一斉配信はできるけれど、現在の設定や運用が正しいか自信がない」 「Zoho CRMとZoho Campaignsのどちらから配信すればよいか分からない」 「リストとセグメントの違いや、配信停止の扱いを整理したい」

    • Next Page