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

      • Can I export all attachments from Zoho CRM?

        Can I export all attachments from Zoho CRM?

      • Community Digest — Noviembre y Diciembre 2025

        ¡Hola, Comunidad de Zoho en Español! Cerramos el año de la mejor forma con nuestro último Community Digest de 2025, donde podrás encontrar las últimas novedades de nuestros productos. ¿Todo listo para empezar 2026 con el mejor pie? ¡Vamos a ello! Zoho

      • Zoho Projects Plus’ 2025- the year we launched

        We’ve been building project management tools for the past 19 years, and a question we often hear is: Different teams in our organization prefer different project management methods; while the development team prefers agile, the marketing and sales teams

      • Zoho Books emails suddenly going to Spam since 11 Nov 2025 (Gmail + now Outlook) — anyone else?

        Hi everyone, We migrated to Zoho Books in July 2025 and everything worked fine until 11 Nov 2025. Since then, Zoho Books system emails are landing in customers’ Spam (first Gmail, and now we’re seeing Outlook/Office 365 also starting to spam them). Impacted

      • How do you print a refund check to customer?

        Maybe this is a dumb question, but how does anyone print a refund check to a customer? We cant find anywhere to either just print a check and pick a customer, or where to do so from a credit note.

      • Company Multiple Branch/ Location Accounting

        Hi All, anyone know whether company can maintain their multiple Branch Accounting in Zoho  Books. It will be chart of Accounts & Master Data will be same but different report available as per per Branch. Thanks & regards, Vivek +91 9766906737

      • Zoho Books Invoices Templates

        It would be really helpful to have more advanced features to customise the invoice templates in Zoho Books. Especially I´m thinking of the spacing of the different parts of the invoice (Address line etc.). If you have a sender and receiver address in

      • Email Administrators! Join our tips & troubleshooting series

        Greetings to all the admins out there! This announcement is exclusively for you. As we step into the New Year, we’re excited to start a dedicated series of admin-specific tips curated to support you. These posts will help you overcome everyday challenges

      • Free Webinar : Unlock AI driven business insights with Zoho Inventory + Zoho Analytics

        Are you tired of switching between apps and exporting data to build customized reports? Say hello to smarter & streamlined insights! Join us for this exclusive webinar where we explore the power of the Zoho Inventory–Zoho Analytics integration. Learn

      • Import Function: ONLY update empty fields

        When setting up an import from a spreadsheet to CRM, there is a checkbox "Don't update empty values for existing contacts" (see screenshot below). While I see some limited benefit from this functionality, I think there should also be an "ONLY update empty

      • Begin the year with best practices in the Zoho Desk mobile app : Part 2

        In focus: Optimizing collaboration and supervision Let's begin 2026 with Part 2 of our tips series on driving your ticketing operations at your fingertips. In Part 1, we explored streamlining operations within tickets. This helped individuals at Omniserve

      • How to update "Lead Status" to more than 100 records

        Hello Zoho CRM, How do I update "Lead Status" to more than 100 records at once? To give you a background, these leads were uploaded or Imported at once but the lead status record was incorrectly chosen. So since there was a way to quickly add records in the system no matter how many they are, we are also wondering if there is a quicker way to update these records to the correct "Lead Status". I hope our concern makes sense and that there will be a fix for it. All the best, Jonathan

      • JWT Token authentication problem that sometimes generates infinite redirect loops

        Description : Nous proposons un bouton sur notre plateforme permettant de rediriger l'utilisateur vers le portail ZohoDesk via un jeton JWT pour une authentification transparente. Cependant, il arrive que certains utilisateurs soient pris dans une boucle

      • ZOHO Work Drive Back Up

        I am looking for a ZOHO Work Drive backup solution. Something that is cloud based. There's lots of these kinds of options for Google Drive and other providers, but I have not seen anything for WorkDrive. Any suggestions?

      • ZOHO Reports - Filter Logic?

        Hi, I need a way to apply filter logics such as ((1 AND 2) OR 3). All I can see as of now is a way to enter different AND filters in the respective filter column. But how can I add an OR filter? Any advice would be highly appreciated. Mark

      • Scanned Doc - selecting Item overwrites Rate

        I have a Vendor Invoice which was uploaded to Documents. I select Add To > New Bill. The OCR is actually quite good, but it is reading an Item Description instead of an Item Number. I remove the description and select the correct Item Number... and it

      • Recruit API search

        Hi all, Attempting to call the search api endpoint from Postman using the word element as mentioned in api docs Search Records - APIs | Online Help - Zoho Recruit When making the call to /v2/Candidates/search?word=Saudi receive response of { "code": "MANDATORY_NOT_FOUND",

      • Saving reading position + Keep screen on

        While Zoho Notebook is excellent for saving and annotating articles, its utility is severely limited by the lack of reading progress synchronization. On the Android app, if a user exits a long note after reading 50%, the app fails to save the position.

      • Multiple Vendor SKUs

        One of the big concerns we have with ZOHO Inventory is lack of Vendor Skus like many other inventory software packages offer. Being able to have multiple vendor skus for the same product would be HUGE! It would populate the appropriate vendor Sku for

      • Zoho LandingPage is integrated with Zoho One!

        Greetings to the Zoho One users out there! We're delighted to let you know that Zoho LandingPage is available in Zoho One too! With Zoho LandingPage, you can host custom-made landing pages, and persuade the visitors to dive deeper by making further clicks,

      • Android app sync problem - multiple devices have same problem

        Hello, I am having a problem with synchronization in the Android app. When I create a drawing, the data does not sync correctly—only a blank note is created without the drawing. I tested this on multiple devices, including phones and tablets, and the

      • How can i resend a campaign to only one of the recipients on the original campaign

        How can i resend a campaign to only one of the recipients on the original campaign ? Sincererly, Mike

      • How to show branch instead of org name on invoice template?

        Not sure why invoices are showing the org name not the branch name? I can insert the branch name using the ${ORGANIZATION.BRANCHNAME} placeholder, but then it isn't bold text anymore. Any other ideas?

      • Marketing Automation Requirements Questions

        I would like to set up a multi-email drip campaign- please see the structure below and confirm if I can achieve this set up in Zoho marketing automation. Where applicable, highlight gaps and workarounds. Thanks Drip email campaign- Can I create one drip

      • Question about using custom_fields in Storefront Add-to-Cart API (error 2003 – required details)

        Hi everyone, I’m working with the Zoho Commerce Storefront API, specifically the Add to Cart endpoint: POST /storefront/api/v1/cart According to the documentation, this endpoint supports a custom_fields parameter for adding line-item custom data. I’m

      • Can a project be cloned?

        Good afternoon, greetings. I would like to ask if it's possible to clone a project in Microsoft Project. I found a way to do it using templates, but I'm not sure if there's a direct way to clone a project. Thank you in advance for your attention, and

      • Timesheet Tasks in Zoho Books: associate to service item

        How do we associate a service item to timesheet tasks in Zoho Books? For example: Joe spent 5 hours on project:task1 which is Service Item#1 (Income:Service1). When the invoice is issued thru the Project Invoice section, this is not available. When the

      • Task/Activity indicator in SalesPipeline overview has disappeared

        I Just logged in my ZOHO CRM first 2026 checking my salespipeline overview , Every record card used to show an indication that there was an open task (Yellow if the expiry date was close, red if the expiry date was today and grey when it had expired).

      • Tip #56- Accessibility Controls in Zoho Assist: Hearing- 'Insider Insights'

        As we begin the new year, it’s a great time to focus on making our tools more inclusive and accessible for everyone. Remote support often involves long hours in front of screens, varying lighting conditions, and users with diverse accessibility needs.

      • Zoho Desk Android app update: Table view for All Departments view, custom button

        Hello everyone! In the latest version(v2.9.25) of the Zoho Desk Android app update, we have introduced Table view for the 'All Departments' view in the ticket module. We also have supported an option that allows tickets in the Table view to be sorted

      • What's New - December 2025 | Zoho Backstage

        In December, Backstage introduced a focused set of updates that improve how you manage registrations, communicate with attendees, and track participation. These enhancements are designed to give organizers greater flexibility and clearer control across

      • Add multiple users to a task

        When I´m assigning a task it is almost always related to more than one person. Practical situation: When a client request some improvement the related department opens the task with the situation and people related to it as the client itself, the salesman

      • A Roundup of Zoho Sprints 2025

      • Sorting Custom Date in API isn't working w pagination limit

        How can we sort a custom field with DATE using pagination? Starting at page=1 then moving to page=2 with a limit of 10 each, its all messed up and even shows some of the same records as page 1? https://www.zohoapis.com/crm/v2/INVOICE_MODULE/search?criteria=(FM_Contact_ID:equals:1234)&sort_by=Invoice_Date&sort_order=desc&per_page=10&page='

      • SAP Business One(B1) integration is now live in Zoho Flow

        We’re excited to share that SAP Business One (B1) is now available in Zoho Flow! This means you can now build workflows that connect SAP B1 with other apps and automate routine processes without relying on custom code. Note: SAP Business One integration

      • Enhancement in Role and Profile mapping of agents in Sandbox

        Hello everyone! We have brought in a modification in the way users are mapped to a particular role and profile in Sandbox. What has changed? When agents are copied from production to Sandbox: If a user's current role and profile is available in Sandbox,

      • The reason I switched away from Zoho Notebook

        My main reason for switching to Zoho was driven by three core principles: moving away from US-based products, keeping my data within India as much as possible, and supporting Indian companies. With that intent, I’ve been actively de-Googling my digital

      • Decimal places settings for exchange rates

        Hello, We are facing issues while matching vendor payments with banking feeds. As we often import products/services exchange rate comes into play. Currently, ZOHO allows only six digits for decimal places. We feel that conversions like JPY to INR require

      • Zoho removed ability to see all Scheduled Reports!

        If you are not the owner of a scheduled report, Zoho recently removed the capability to see each scheduled report. As an admin who relies on seeing all scheduled reports being sent, this is a terrible update. Now I cannot see ANY scheduled reports...even the ones I am being sent!!  This should be a setting for admins to control.  This is a bad update.

      • Automate Backups

        This is a feature request. Consider adding an auto backup feature. Where when you turn it on, it will auto backup on the 15-day schedule. For additional consideration, allow for the export of module data via API calls. Thank you for your consideration.

      • Next Page