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

    • Adding bank details to the contact through API

      How to add bank-related information to the contact while creating it using API? The account number needs to be encrypted before sending it through API but not sure how to encrypt and get those values. Please guide me in this.

    • Font breakage in Zoho Mail Desktop Lite application for Mac

      Dear Zoho Mail and Workplace Community, With the latest update of macOS Sequoia and macOS Tahoe, there has been font breakages in the email preview of Zoho Mail Desktop Lite application for Mac. This breakage is due to the corruption of the System fonts

    • Feature request - image resizing on sales orders

      I need to be able to show the items on the sales orders, currently the item image shows really small and no way to resize it, need the ability to make the image larger to showcase the product on the pdfs

    • Nueva edición de "Ask The Expert" en Español Zoho Community

      ¡Hola Comunidad! ¿Te gustaría obtener respuestas en directo sobre Zoho CRM, Zoho Desk u otra solución dentro de nuestro paquete de CX (Experiencia del Cliente? Uno de nuestros expertos estará disponible para responder a todas tus preguntas durante nuestra

    • Automation Series: Auto-Notify External Users on Issue Closure

      Hello Folks! In Zoho Projects, you can notify external issue reporters via email when an issue is marked as Closed. This helps the users avoid manual follow-ups and keeps the reporter updated. In this post, we’ll walk through a simple setup using a Web

    • Turn chat conversations into real action with Integration Blocks in Guided Conversations

      When a Guided Conversation fails, it's usually not because the logic is wrong. They fail because the conversation stops moving. A customer starts a chat with a clear goal: report an issue, check a status, or confirm something. At first, the flow does

    • Basic Mass Update deluge schedule not working

      I'm trying to create a schedule that will 'reset' a single field to 0 every morning - so that another schedule can repopulate with the day's calculation. I thought this would be fairly simple but I can't work out why this is failing : 1) I'm based in

    • click to call feature

      I've Zoho CRM and in that i want click to call feature.

    • We Asked, Zoho Delivered: The New Early Access Program is Here

      For years, the Zoho Creator community has requested a more transparent and participatory approach to beta testing and feature previews. Today, I'm thrilled to highlight that Zoho has delivered exactly what we asked for with the launch of the Early Access

    • Can the Product Image on the Quote Template be enlarged

      Hello, I am editing the Quote Template and added ${Products.Product Image} to the line item and the image comes up but it is very tiny. Is there anyway that you can resize this to be larger? Any help would be great! Thanks

    • Creating Parent Child relationship in Accounts

      We have customers with multiple locations, I setup the HQ as an account, then I setup the different sites marking the HQ as the parent to that location. If I then do a Deal for one of the locations, is there a way to show by looking at the parent account

    • Learner transcript Challenges.

      Currently i am working on a Learner Transcript app for my employer using Zoho Creator. The app is expected to accept assessment inputs from tutors, go through an approval process and upon call up, displays all assessments associated with a learner in

    • Client and Vendor Portal

      Some clients like keeping tabs on the developments and hence would like to be notified of the progress. Continuous updates can be tedious and time-consuming. Zoho Sprints has now introduced a Client and Vendor Portal where you can add client users and

    • need a packing list feature

      In our business, goods listed on an invoice are packed in separate boxes and shipped off. for e.g. an invoice may have 10 items. each item could then be packed in different boxes depending on qty of each item. this packing list is as important as the invoice for purposes of shipping documents.  Request you to add this feature asap.

    • Recording the deducted TDS on advance received from Customer (Zoho Books India)

      Hi, How can we record the tds that has been deducted by my customer for the advance that he has paid to me. 1) My customer has paid Rs 10000 to me as advance (Rs 9800 as cash and deducted Rs 200 as TDS). I am not able to record the tds that has been deducted

    • #7 Tip of the week: Delegating approvals in Zoho People

      With Zoho People, absences need not keep employees waiting with their approval requests. When you are not available at work, you can delegate approvals that come your way to your fellow workmate and let them take care of your approvals temporarily. Learn more!

    • Admin Tip: Manage sub-domain emails using sub-domain stripping

      As an admin, you may need separate domains for different departments such as sales, support, and marketing. While this approach offers flexibility, creating and managing multiple domains can quickly become overwhelming, especially since each domain requires

    • Quick Copy Column Name

      Please add the ability to quickly copy the name of a column in a Table or Query View. When you right-click the column there should be an option to copy the name, or if you left-click the column and use the Ctrl+C keyboard shortcut it should copy the

    • Ability to Edit YouTube Video Title, Description & Thumbnail After Publishing

      Hi Zoho Social Team, How are you? We would like to request an enhancement to Zoho Social that enables users to edit YouTube video details after the video has already been published. Your team confirmed that while Zoho Social currently allows editing the

    • How do I remove a data source from Zoho Analytics?

      I am unable to find a delte option on a datasource that i put in the system as an error. On teh web it refers to a setup icon but I do not see that on my interface?

    • Add Employee Availability Functionality to Zoho People Shift Module

      Hello Zoho People Product Team, Greetings and hope you are doing well. We would like to submit a feature request to enhance the Zoho People Shift module by adding employee availability management, similar to the functionality available in Zoho Shifts.

    • Bigin, more powerful than ever on iOS 26, iPadOS 26, macOS Tahoe, and watchOS 26.

      Hot on the heels of Apple’s latest OS updates, we’ve rolled out several enhancements and features designed to help you get the most from your Apple devices. Enjoy a refined user experience with smoother navigation and a more content-focused Liquid Glass

    • Delay in rendering Zoho Recruit - Careers in the ZappyWorks

      I click on the Careers link (https://zappyworks.zohorecruit.com/jobs/Careers) on the ZappyWorks website expecting to see the job openings. The site redirects me to Zoho Recruit, but after the redirect, the page just stays blank for several seconds. I'm

    • Is Desk Down?

      Across department - always an error. [Status Mode] - error [Table View and the rest] - working

    • How do I change the wording of the tile of SignForm?

      When my user opens a SignForm url, the title that is presented is always "SignForm signer Information" and a form is displayed asking for the username and email address. This can be confusing to the end user. How can I change the title at least (Or at

    • How to link tickets to a Vendor/Vendor Contact (not Customer) for Accounting Department?

      Hi all, We’re configuring our Accounting department to handle tickets from both customers and vendors (our independent contractors). Right now, ticket association seems to be built around linking a ticket to a Customer / Customer Contact, but for vendor-originated

    • Automatic Matching from Bank Statements / Feeds

      Is it possible to have transactions from a feed or bank statement automatically match when certain criteria are met? My use case, which is pretty broadly applicable, is e-commerce transactions for merchant services accounts (clearing accounts). In these

    • Unify Overlapping Functionalities Across Zoho Products

      Hi Zoho One Team, We would like to raise a concern about the current overlap of core functionalities across various Zoho applications. While Zoho offers a rich suite of tools, many applications include similar or identical features—such as shift management,

    • Automation #7 - Auto-update Email Content to a Ticket

      This is a monthly series where we pick some common use cases that have been either discussed or most asked about in our community and explain how they can be achieved using one of the automation capabilities in Zoho Desk. Email is one of the most commonly

    • Ticket to article and Ticket to template

      Hello! I would like to know if it is possible (and how) to do the following actions: 1. To generate an article from a ticket (reply + original message) 2. Easy convert an answer to an email template

    • Is there API Doc for Zoho Survey?

      Hi everyone, Is there API doc for Zoho Survey? Currently evaluating a solution - use case to automate survey administration especially for internal use. But after a brief search, I couldn't find API doc for this. So I thought I should ask here. Than

    • Kaizen #225 - Making Query-based Custom Related Lists Actionable with Lookups and Links

      Hello everyone! Welcome back to another post in the Kaizen series! This week, we will discuss an exciting enhancement in Queries in Zoho CRM. In Kaizen #190, we discussed how Queries bridge gaps where native related lists fall short and power custom related

    • WebDAV / FTP / SFTP protocols for syncing

      I believe the Zoho for Desktop app is built using a proprietary protocol. For the growing number of people using services such as odrive to sync multiple accounts from various providers (Google, Dropbox, Box, OneDrive, etc.) it would be really helpful

    • Change the "from" field

      Hello, I used some random word to create the account ID to later host the domain based emails. That username shows up in the "from" field on test emails. How do I change that to a custom one, like first name/last name or business name? I tried to create second user and "named" it the way I want and it worked to a degree, although the "from" field shows all lower case letters, while original had some capital letters. So the "all-low-case" is another issue I am having... Thank you

    • [Free Webinar] Learning Table Series - AI-Enhanced Logistics Management in Zoho Creator

      Hello Everyone! We’re excited to invite you to another edition of Learning Table Series, where we showcase how Zoho Creator empowers industries with innovative and automated solutions. About Learning Table Series Learning Table Series is a free, 45-60

    • How to use Rollup Summary in a Formula Field?

      I created a Rollup Summary (Decimal) field in my module, and it shows values correctly. When I try to reference it in a Formula Field (e.g. ${Deals.Partners_Requested} - ${Deals.Partners_Paid}), I get the error that the field can’t be found. Is it possible

    • Zoho Creator to Zoho CRM Images

      Right now, I am trying to setup a Notes form within Zoho Creator. This Notes will note the Note section under Accounts > Selected Account. Right now, I use Zoho Flow to push the notes and it works just fine, with text only. Images do not get sent (there

    • Error Logs / Failure logs for Client Scripts Functions

      Hi Team, While we are implementing client scripts for the automation, it is working fine in few accounts but not working for others. So, it would be great if we can have error Logs for client scripts also just like custom functions. Is there any way that

    • Zoho Books blocks invoicing without VeriFactu even though it is not mandatory until 2027

      I would like to highlight a very serious issue in Zoho Books for Spain. 1. The Spanish government has postponed the mandatory start of VeriFactu to January 1st, 2027. This means that during all of 2026 businesses are NOT required to transmit invoices

    • Problem : Auto redirect from zoho flow to zoho creator

      Hi there, I've been waiting for zoho team to get back on this for last couple of days. Anyone else have the problem to access zoho flow? everytime I click on zoho flow it redirects me to zoho creator. I tried incognito mode but it still direct me to zoho

    • Next Page