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

    • Passing the CRM

      Hi, I am hoping someone can help. I have a zoho form that has a CRM lookup field. I was hoping to send this to my publicly to clients via a text message and the form then attaches the signed form back to the custom module. This work absolutely fine when
    • I want to test some payment subscription with a test credit card from stripe

      I have a test customer and place https://stripe.com/docs/testing#international-cards test credit card number to the Add New Card in subscription.zoho customer page. After I added, the test card was declined. Am I missing something?
    • This user is not allowed to add in Zoho. Please contact support-as@zohocorp.com for further details

      Hello, Just signed up to ZOHO on a friend's recommendation. Got the TXT part (verified my domain), but whenever I try to add ANY user, I get the error: This user is not allowed to add in Zoho. Please contact support-as@zohocorp.com for further details I have emailed as well and writing here as well because when I searched, I saw many people faced the same issue and instead of email, they got a faster response here. My domain is: raisingreaderspk . com Hope this can be resolved.  Thank you
    • Strengthen your account security with Password Policy

      Still using the same password for all your accounts? Or perhaps your password is easy to guess or follows a predictable pattern? If so, your account could be at risk. Once someone gets hold of a password that you reuse, they could potentially gain access
    • Expanding sales, marketing, and support capabilities in Zoho CRM Plus 3.0

      Hey everyone, It's been more than 10 years since we launched Zoho CRM Plus back in 2014. This is quite a milestone, and we've come a long way in empowering you with everything you need to offer an exceptional customer experience. On that note, we expanded
    • Introducing PRM: Build, manage, and scale your partner ecosystem

      Growing a partner ecosystem is a good problem to have. What starts as a handful of partners can quickly turn into a maze of spreadsheets, emails, and disconnected processes. More partners mean more opportunities, greater reach, and new ways to grow
    • Live connection to DS files in Zoho Creator / ChatGPT

      As an idea, we are using ChatGPT to build with Zoho Creator (outside of Zia), which is works brilliantly to assist write deluge, provide test suggesitons etc. Currently we are uploading the DS files which are very point in time, it would be great to have
    • Zoho Forms - Feature Request - Embed iFrame or Dynaic URLs in Description fields

      Hi Zoho Forms team, I'm working with a client who uses Zoho Forms internally to collect information over the phone from potential work placement candidates. At the end of the form, the candidate needs to be booked in for an induction, which we've configured
    • New in Office Integrator: Add text, diagrams, and drawings to your spreadsheet

      Hi users, We are pleased to introduce the Shapes feature in Zoho Office Integrator's spreadsheet editor. It lets users create visual elements; including simple shapes, text boxes, freehand drawings, and structured diagrams; directly within the spreadsheet.
    • Highlight what matters, erase what doesn’t in PDFs

      When reviewing PDFs or preparing them for sharing, two things often come up: you want to draw attention to what’s important, and you want to hide what isn’t. Zoho PDF Editor gives you both capabilities in one place with its highlight and erase tools.
    • WorkDrive Desktop Sync Is Being Deprecated: Move to WorkDrive TrueSync for a Smarter Experience

      Hi everyone, We are excited to share a better, smarter way to access and manage your files directly from your computer! We’re transitioning from our legacy Desktop Sync app to WorkDrive TrueSync, designed to give you faster performance,greater flexibility,
    • Set connection link name from variable in invokeurl

      Hi, guys. How to set in parameter "connection" a variable, instead of a string. connectionLinkName = manager.get('connectionLinkName').toString(); response = invokeurl [ url :"https://www.googleapis.com/calendar/v3/freeBusy" type :POST parameters:requestParams.toString()
    • Introducing the Zoho Campaigns MCP server

      Hello everyone, We are pleased to announce that Zoho Campaigns is now available in Zoho MCP. You can now connect your Zoho Campaigns organization to AI tools such as Claude, ChatGPT, GitHub Copilot in VS Code, and Cursor, and manage your email marketing
    • SubForm Custom Sort - Deluge Workflows

      I have been experimenting with the Custom Order function of Subforms, it works beautifully within the subform itself and retains the sorting order. However, I need to be able to iterate through the records in Deluge using the sort order (The usage case
    • Bank feeds automation is broken - requires manual intervention and authentication

      Yodlee supports Australian Open Banking CDR protocols natively, but Zoho Books' implementation is still triggering legacy screen-scraping MFA blocks on CBA and other business banking accounts. When will Zoho update its Australian bank feed pipeline to
    • Cannot Access Subform Display Order in Deluge

      As highlighted in this community post, we still have to deal with the significant limitation of not being able to access the user-sorted order of subform rows through Deluge. This creates a major disconnect between the UI capabilities and backend automation,
    • Process FOR loop for subform items in the order of the manual sorting

      Hi Guys, I have searched everywhere and tried everything, but I still not able to resolve one particular challenge. I have a subform in my Invoice with rows for each item. I made it so that we can change the order of the items manually. I need to be able
    • Augmenting subform capabilities

      Greetings, everyone! Finally, the day has come for us to announce some of the most anticipated, requested, and exciting updates to subforms in Zoho Creator. As you're aware, subforms are an integral part of Creator forms, as they help in establishing
    • Build appointment scheduling into your vibe-coded apps with Zoho Bookings

      Exploring vibe coding? Wondering how an app built with AI can handle appointment scheduling? Join our upcoming live webinar to discover how Zoho Bookings APIs can help connect applications to scheduling capabilities. Here's what we'll explore: • Show
    • Is there a way to make Reason For Loss field mandatory at Closed Lost stage?

      Hi guys, Reason For Loss system picklist appears on Verify Details page but it is not mandatory so as a result, AEs tend to omit it (leave at default value -None-). Is there a way to make it mandatory at Closed Lost? I tried layout rule but this field
    • How to customize the displayed name of contacts in Trident?

      Hello, For work purposes, I sort different customers into different folders, and I also change their display names in Contacts so I can easily recognize them later. However, Trident doesn’t seem to support this. Even after I edit a contact’s name in Contacts,
    • User and mailbox reports in Zoho Mail: Review account status, storage, and login activity of users

      Administrators often need answers to questions such as which users have never logged in, whose storage is almost full, or which mailboxes are accessed through POP or IMAP. The User and Mailbox reports in the Zoho Mail Admin Console provide these details
    • ZOHO CRM APP - SALESINBOX

      Is it possible to access SALESINBOX in the CRM MOBILE APP
    • Unbundle feature for composite items

      We receive composite items from our vendors and sell them either individually or create other composite items out of them. So, there is a lot of bundling and unbundling involved with our composite items. Previously, this feature was supported in form
    • Zoho mail always free not showing up for me

      Im in the Australian data centre region
    • Tip #96 – See more of the remote screen with Virtual Monitor – 'Insider Insights'

      Hello Zoho Assist Community! Say you're supporting a device that has no monitor attached, like a server in a closet or a kiosk PC. You connect, and the screen is tiny, blurry, or distorted. Text overlaps and windows end up in odd places. Troubleshooting
    • Understanding transactional channels in Zoho CPaaS

      Every interaction with a business creates an opportunity to communicate.Whether it's welcoming a new user, confirming a payment, sharing an order update, or verifying a login, timely communication keeps users informed and connected. But how do businesses
    • Autoscan Settings

      I saw that autoscan is now included in my plan which is great however when I import pdf invoices from my main supplier which contain inventory lines and some also include shipping charges the autoscan doesn't match any of the items and also misses the
    • How to resubscribe to email after using unsubscribe link in Zoho

      I was testing the unsubscribe link feature from our contacts module in ZohoCRM and I sent my personal email a version of an email template with the default embedded unsubscribe link to see if it would utilize the "Email Opt Out" field to track un-subscription.
    • WhatsApp Calling Integration via Zoho Desk

      Dear Zoho Desk Team, I would like to request a feature that allows users to call WhatsApp numbers directly via Zoho Desk. This integration would enable sending and receiving calls to and from WhatsApp numbers over the internet, without the need for traditional
    • [ZohoDesk] Improve Status View with a new editeble kanban view

      A kanban view with more information about the ticket and the contact who created the ticket would be valueble. I would like to edit the fields with the ones i like to see at one glance. Like in CRM where you can edit the canvas view, i would like to edit
    • No access to contact categories in Zoho Mail Apps

      I have set up a number of contact categories for my organization. When I compose an email using a web browser these categories are visible. When I compose an email using your Android or iOS Apps no contact categories are visible. Is this expected? If
    • Zoho Plug In

      Is there anyone out there who is able to use it? I have seen lots of problems posted, unable to get any satisfactory suppport at the moment!  I would be really appreciate hearing from users that have it installed and working, my team are loosing belief it will ever work. Be great to hear from those that have a more positive experience
    • Outlook to Zoho sync

      I am the admin for our company and I have (1) single user that is having difficulties with her emails syncing. I have found where the problem is, but I don't know 100% if what is happening is how the plug-in works or if it's a setup issue. My boss created
    • Cant' find the CRM plug in for outlook

      I want to be able to tag emails that I have received into accounts. But I can't find the plug in for out look in the other apps section.  Where can I download it from?
    • Problems with Zoho CRM Microsoft Outlook Plug-In (Add-On)

      I am having problems with the Zoho CRM Microsoft Outlook Plug-In.  I was able to install and setup the Plug-In correctly I believe in Microsoft Outlook, but contacts are now being created in Zoho CRM when an email is sent from MS Outlook.  A contact is created and appears under Contacts in Zoho CRM but no other information is populated in the fields; for instance only the name is there (for instance "rfairley" ) which matches the beginning of their email address; but no phone numbers.    Also, other
    • zoho for outlook

      it would be woderfull to be able to add an email to a case, just as it is possible to add an email to a potential Vincent
    • Mail Addon issue

      Hi, I am trying  to make the mail add on feature work without clutter. The issues is that all emails from the contact are being listed in every opportunity that contact is involved in/ linked to.  I want to filter out the emails that are not relevant to the opportunity. It is ok to have all the mails of a contact under in the contact module. But under the opportunity it shall show only the relevant emails. Is there a way i could do this? Atleast if I could manually assign or amend the listed emails
    • Eliminate duplicate tickets in one department using Email Deduplication ​

      Hello everyone, A department can have multiple email addresses designed for different purposes for example, support@zpad.com and help@zpad.com. When a customer sends an email or thread response to both addresses, or includes both in the To, CC, or BCC
    • "Pinning" a Note

      It would be really helpful to have a way to "Pin" a note to the top of the notes section. This is really important when you have something important about someone and do not want the note to get buried farther and farther down the note stream. For instance:
    • Next Page