Associate Email with a Record

Zoho CRM allows its users to associate emails with record entities. You can also associate an email entry with a record, and map another record to the same. For example, if you are associating an email to a Deal, you might also need to map a contact with it. This is facilitated using the associate email API.

Purpose

To associate an email with a record entity in Zoho CRM.

Endpoints

POST /{module_API_name}/{entity_ID}/actions/associate_email

Request Details

Request URL

{api-domain}/crm/{version}/{module_API_name}/{record_ID}/actions/associate_email

Supported modules

Leads, Contacts, Quotes, Invoices, Sales_Orders, Purchase_Orders, Deals, Accounts and Custom

Header

Authorization: Zoho-oauthtoken d92d4xxxxxxxxxxxxx15f52

Scope

ZohoCRM.modules.emails.ALL
(AND)
ZohoCRM.modules.{module}.ALL

Possible modules

Leads, Contacts, Quotes, Invoices, Sales_Orders, Purchase_Orders, Deals, Accounts and Custom modules.

Sample Request

Copiedcurl "https://www.zohoapis.com/crm/v8/Deals/4876876000000333267/actions/associate_email"
-X POST
-d "assoc-email.json"
-H "Authorization: Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"

Input JSON

fromJSON object, mandatory
Represents the sender of the email. The object includes user_name and email.
toJSON array, mandatory
Represents the recipients of the email. Each object in the array includes user_name and email.
subjectstring, mandatory
Represents the subject line of the email.
contentstring, mandatory
Represents the email body content.
date_timeDateTime, mandatory
The date and time at which the email was sent.
sent Boolean, mandatory
Represents whether the email was sent or received.
Possible values:
true - The email was sent.
false - The email was received.
original_message_idstring, mandatory
Represents the unique message ID from the email header.
ccJSON array, optional
Represents the users to whom the associated email is addressed in cc. The object consists of user_name and email.
bccJSON array, optional
Represents the users to whom the associated email is addressed in bcc. The object consists of user_name and email.
mail_formatstring, optional
Represents format of the associated email. Possible value is html.
attachmentsJSON array, optional
Includes details of the attachments in the email. Each object contains the id and file_name. The id represents the file ID after uploading the file to ZFS. Please refer to Upload Files documentation for more details. Please not that the total size limit on attachment file(s) is 10MB.
linked_recordJSON object, optional
Maps the email to an additional entity. This object contains the id and name of the entity, and the module details.

Sample Input

Copied{
  "Emails": [
    {
      "from": {
        "user_name": "user1",
        "email": "test@zoho.com"
      },
      "to": [
        {
          "user_name": "user2",
          "email": "test1@zoho.com"
        }
      ],
      "cc": [
        {
          "user_name": "user3",
          "email": "test2@zoho.com"
        }
      ],
      "bcc": [
        {
          "user_name": "user4",
          "email": "test3@zoho.com"
        }
      ],
      "subject": "Mail subject",
       "content": "<h3><span style=\"background-color: rgb(254, 255, 102)\">Mail is of rich text format</span></h3><h3><span style=\"background-color: rgb(254, 255, 102)\">REGARDS,</span></h3><div><span style=\"background-color: rgb(254, 255, 102)\">AZ</span></div><div><span style=\"background-color: rgb(254, 255, 102)\">ADMIN</span></div> <div></div>", 
      "mail_format": "html",
      "date_time": "2018-06-12T12:12:12+05:30",
      "sent": true,
       "attachments": [
        {
          "id": "39c17f1033cd120e62f8104c545af0ef95a1bd5438fe9159ee8ff6d1bee480cd",
          "name": "Test File"
        }
      ],
       "linked_record": {
         "id" : "4876876000001355087",
         "name" : "Simmons Truhlar",
         "module": {
          "api_name": "Contacts",
          "id": "4876876000000002179"
         }             
    },
      "original_message_id": "1234534dead-asds3322w243"
    }
  ]
}

Request format for content with inline image

If you want the associated email content to include an inline image, you should upload the image to ZFS with the parameter type=inline. The file ID from the response should be used in the content section of the input body. For more details, kindly check the Sample Input section towards the right.

Sample Input for content with Inline Image

Copied{
  "Emails": [
    {
      "from": {
        "user_name": "user1",
        "email": "test@zoho.com"
      },
      "to": [
        {
          "user_name": "user2",
          "email": "test1@zoho.com"
        }
      ],
      "cc": [
        {
          "user_name": "user3",
          "email": "test2@zoho.com"
        }
      ],
      "bcc": [
        {
          "user_name": "user4",
          "email": "test3@zoho.com"
        }
      ],
      "subject": "Inline Image Content",
       "content": "<br><br><br><br>Hi Inline image<br><br><h3><span style=\"background-color: rgb(254, 255, 102)\"><img class=\"ZCrmImage\" src=\"crm\/img_id:39c17f1033cd120e62f8104c545af0ef3933f668cfda215fbe50a2cc5226de1d\"></span></h3><h3><span style=\"background-color: rgb(254, 255, 102)\">REGARDS,</span></h3><div><span style=\"background-color: rgb(254, 255, 102)\">AZ</span></div><div><span style=\"background-color: rgb(254, 255, 102)\">ADMIN</span></div> <div></div>", 
      "mail_format": "html",
      "date_time": "2018-06-12T12:12:12+05:30",
      "sent": true,
      "original_message_id": "1234523asad-asds23324374"
    }
  ]
}

Request format for users with admin role to associate other user's mail

An admin user can associate other user's email with any record. Please note that only users with admin privilege can associate another user's email with a record. You need to give an extra input key to represent the owner of the email.

Input JSON

ownerJSON object, mandatory if associating other user's email.
Represents the owner of the email.

Sample Input for admin user to associate other user's mail

Copied{
  "Emails": [
    {
      "from": {
        "user_name": "user1",
        "email": "test@zoho.com"
      },
      "to": [
        {
          "user_name": "user2",
          "email": "test1@zoho.com"
        }
      ],
      "cc": [
        {
          "user_name": "user3",
          "email": "test2@zoho.com"
        }
      ],
      "bcc": [
        {
          "user_name": "user4",
          "email": "test3@zoho.com"
        }
      ],
      "owner" : {
          "id" : "4876876000001360001"
      },
      "subject": "Other User email",
      "content": "<h3><span style=\"background-color: rgb(254, 255, 102)\">Mail is of rich text format</span></h3><h3><span style=\"background-color: rgb(254, 255, 102)\">REGARDS,</span></h3><div><span style=\"background-color: rgb(254, 255, 102)\">AZ</span></div><div><span style=\"background-color: rgb(254, 255, 102)\">ADMIN</span></div> <div></div>",
      "mail_format": "html",
      "date_time": "2018-06-12T12:12:12+05:30",
      "sent": false,
       "attachments": [
        {
          "id": "39c17f1033cd120e62f8104c545af0ef95a1bd5438fe9159ee8ff6d1bee480cd",
          "name": "Test File"
        }
      ],
      "original_message_id": "1234534frad-aers2332w243"
    }
  ]
}

Possible Errors

INVALID_REQUEST_METHODHTTP 400
The request method is incorrect.
Resolution: Use the HTTP POST method to make this API call. Any other request method will result in this error.
FILE_SIZE_EXCEEDSHTTP 400
Total file(s) size should not exceed 10MB. The file size is exceeding this limit.
Resolution: Limit the total attachment file size to 10MB.
DUPLICATE_DATAHTTP 400
The message ID you have specified is already associated with the record.
Resolution: Specify another valid message ID for original_message_id key.
INVALID_DATAHTTP 400
- You have specified an invalid attachment ID.
  Resolution: Specify a valid attachment ID.
- You have specified an invalid owner ID.
  Resolution: Provide a valid owner ID.
- You have specified an invalid record ID for the linked record.
  Resolution: Provide a valid record ID.
- You have specified an invalid module API name for the linked_records value.
  Resolution: Specify a valid and supported module API name in the linked_records key.
MANDATORY_NOT_FOUNDHTTP 400
You have not specified one or more of the mandatory keys in the input JSON.
Resolution:Please refer to the Input JSON section at the beginning of this page, and specify all mandatory keys.
INVALID_MODULEHTTP 400
You have tried to associate the email with an unsupported module.
Resolution:Check the Supported modules section above to know which all modules are supported, and associate the email with a supported module entity.
STORAGE_ SPACE_EXCEEDSHTTP 400
You have exceeded the storage space of your Zoho CRM Org.
Resolution:Please contact your administrator.
OAUTH_SCOPE_MISMATCHHTTP 401
The access token you have used to make this API call does not have the required scope.
Resolution: Generate a new access token with the required scopes for this API. Refer to the Scope section at the beginning of this page for the list of required scopes.
NO_PERMISSIONHTTP 403
Only Admin Role/Profile Users will have permission
Resolution: Contact your system administrator.
INVALID_URL_PATTERNHTTP 404
The request URL is incorrect.
Resolution: Specify a valid request URL. Refer to the request URL section at the beginning of this page for more details.
INTERNAL_ERRORHTTP 500
Unexpected and unhandled exception in the server.
Resolution: Contact the support team at support@zohocrm.com.

Sample Response

Copied{
    "Emails": [
        {
            "code": "SUCCESS",
            "details": {
                "message_id": "39c17f1033cd120e62f8104c545af0ef3bf9a4d702dd9c006bc737afa46d6975"
            },
            "message": "Your mail has been added successfully",
            "status": "success"
        }
    ]
}