Link Deal to Emails

Zoho CRM automatically links a contact's incoming emails to the deals using the Deal Prediction Mechanism. You can also manage these links using the Link Deal to Emails API and Unlink Deal from Emails API.

Purpose

To link a deal with one or more of a contact's emails.

Note

  • An email can only be linked to a single deal at a time.
  • The user's profile requires "View" permission for Deals and Contacts modules to use this API.

Endpoints

  • POST /Contacts/{contacts_record_ID}/Emails/actions/link_record
  • POST /Contacts/{contacts_record_ID}/Emails/{message_ID}/actions/link_record

Request Details

Request URL

To link a deal to  a contact's multiple emails:
{api-domain}/crm/{version}/Contacts/{contacts_record_ID}/Emails/actions/link_record

To link a deal to a contact's single email:
{api-domain}/crm/{version}/Contacts/{contacts_record_ID}/Emails/{message_ID}/actions/link_record

Header

Authorization: Zoho-oauthtokend92d4xxxxxxxxxxxxx15f52

Scope

ZohoCRM.modules.emails.ALL
(and)
ZohoCRM.modules.contacts.ALL

Sample Request to link a contact's deal to multiple emails

Copiedcurl "https://www.zohoapis.com/crm/v8/Contacts/5843104000000425349/Emails/actions/link_record"
-H "Authorization: Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"
-d @linkdeal.json
-X POST

Input JSON

  • EmailsJSON array

    Contains the details of the email that should be linked to the deal. When multiple emails are to be linked, the details should be provided as separate JSON objects inside this array. When a single email is to be linked, the details should be provided in a single JSON object inside this array along with message_id in path parameter. Refer to sample JSONs for reference. The Emails JSON array must include the following keys:

    • ownerJSON object, mandatory

      Represents the details of the user whose email you want to link.

      • namestring, mandatory

        Represents the name of the user whose email you want to link.

      • idlong, mandatory

        Represents the ID of the user whose email you want to link.

    • message_idstring, mandatory when linking multiple emails

      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.
       

    • linked_recordJSON object, mandatory

      Represents the details of the deal record to be linked to the email.

      • moduleJSON object, mandatory

        Represents the details of the deals module.

        • api_namestring, mandatory

          Represents the API name of the deals module.

        • idlong, mandatory

          Represents the ID of the deals module.

      • namestring, mandatory

        Represents the name of the deal that the email must be linked to .

      • idlong, mandatory

        Represents the ID of the deal record that the email must be linked to .

Sample Input to link a contact's deal to multiple emails

Copied{
    "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"
            }
        }
    ]
}

Sample response when a contact's deal is linked to multiple emails

Copied{
    "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"
        }
    ]
}

Possible Errors

  • INVALID_DATAHTTP 400
    • The value for one of the input keys is invalid.
      Resolution: Specify valid values for the input keys. Refer to the Sample Input section and specify valid input.
    • The data type of the input key is invalid.
      Resolution: Refer to the Sample Input JSON section and specify the valid keys in correct data type.
  • INVALID_MODULEHTTP 400

    The module name given seems to be invalid.
    Resolution: The module name should be Deals.

  • FEATURE_NOT_SUPPORTEDHTTP 400

    Your License does not support this feature.
    Resolution: This API is supported for Zoho CRM editions Standard and above. Upgrade your edition or contact support@zohocrm.com

  • MANDATORY_NOT_FOUNDHTTP 400

    A required field is missing.One or more mandatory fields are missing in the input JSON. The name of the missing field and its location can be found in the message and json_path keys of the error response.
    Resolution: Specify all mandatory fields.

  • NOT_ALLOWEDHTTP 400

    The contact is not associated with the deal.
    Resolution: You must add contact details to the deal to proceed.

  • AMBIGUITY_DURING_PROCESSING HTTP 400

    Ambiguity during processing.
    Resolution:  The module's unique ID and API name seem to be mismatched. Please specify the correct module ID along with its corresponding API name. Use the GET Module Metadata API  to retrieve the API names and IDs of your modules.

  • API_NOT_SUPPORTEDHTTP 400

    The API is not supported in this version.
    Resolution: This API is supported only from Version 8.

  • ALREADY_LINKEDHTTP 400

    The email is already linked.
    Resolution: Unlink the email first to link it to another deal record.

  • OAUTH_SCOPE_MISMATCHHTTP 401

    The access token you have used to make this API call does not have the required scope.
    Resolution: The client does not have a valid scope to link deals. Create a new token with valid scope. Refer to the Scope section.

  • AUTHENTICATION_FAILUREHTTP 401

    Authentication failed.
    Resolution: Pass the access token in the request header of the API call.

  • NO_PERMISSIONHTTP 403

    Permission denied.
    Resolution: Contact your administrator to update profile permissions for your profile through Update Profile Permissions API for Crm_Implied_View_Deals and Crm_Implied_View_Contacts permissions.

  • INVALID_URL_PATTERNHTTP 404

    Please check if the URL trying to access is a correct one.
    Resolution: The request URL specified is incorrect. Specify a valid request URL. Refer to the Request URL section.

  • INTERNAL_ERRORHTTP 500

    Internal Server Error.
    Resolution: Unexpected and unhandled exception in the server. Contact support team.

Sample Request to link a contact's deal to a single email

Copiedcurl "https://www.zohoapis.com/crm/v8/Contacts/5843104000000425349/Emails/6622e532084a2c329b44f4d7c58a93bb2f616d21e1e73cc1e9cc71d24ef6b5f5/actions/link_record"
-H "Authorization: Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"
-d @linkdeal.json
-X POST

Sample Input to link a contact's deal to a single email

Copied{
    "Emails": [
        {
            "linked_record": {
                "module": {
                    "api_name": "Deals",
                    "id": "5843104000000003735"
                },
                "name": "Travel Insurance",
                "id": "5843104000004382122"
            },
            "owner": {
                "name": "Patricia Boyle",
                "id": "5843104000000424672"
            }
        }
    ]
}

Sample response when a contact's deal is linked to a single email

Copied{
    "Emails": [
        {
            "linked_record": {
                "module": {
                    "api_name": "Deals",
                    "id": "5843104000000003735"
                },
                "name": "Travel Insurance",
                "id": "5843104000004382122"
            },
            "owner": {
                "name": "Patricia Boyle",
                "id": "5843104000000424672"
            }
        }
    ]
}