Zoho CRM Associate Email API

{
  "openapi": "3.1.0",
  "info": {
    "title": "Zoho CRM Associate Email API",
    "description": "Associates emails to CRM records and checks availability",
    "version": "8.0"
  },
  "servers": [
    {
      "url": "https://www.zohoapis.com/crm/{version}",
      "description": "Production Server (US)",
      "variables": {
        "version": {
          "default": "v8",
          "description": "API version"
        }
      }
    }
  ],
  "paths": {
    "/{module}/{recordId}/actions/associate_email": {
      "post": {
        "summary": "Associate Email",
        "description": "Associates emails to a specific record in a module.",
        "operationId": "associateEmail",
        "security": [
          {
            "iam-oauth2-schema": [
              "ZohoCRM.modules.emails.CREATE"
            ]
          }
        ],
        "parameters": [
          {
            "name": "module",
            "in": "path",
            "required": true,
            "description": "The API name of the module (e.g., Leads, Contacts).",
            "schema": {
              "type": "string",
              "maxLength": 100
            }
          },
          {
            "name": "recordId",
            "in": "path",
            "required": true,
            "description": "The unique ID of the record to associate the email with.",
            "schema": {
              "type": "string",
              "maxLength": 100
            }
          }
        ],
        "requestBody": {
          "description": "Payload containing the email details to be associated.",
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AssociateEmailRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Email associated successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/ActionResponse"
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Bad Request.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/ErrorResponse"
                    }
                  ]
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "AssociateEmailRequest": {
        "type": "object",
        "description": "Request body for associating an email with a record.",
        "additionalProperties": false,
        "properties": {
          "data": {
            "type": "array",
            "description": "List of email objects to process.",
            "items": {
              "$ref": "#/components/schemas/EmailObject"
            },
            "minItems": 1,
            "maxItems": 50
          }
        },
        "required": [
          "data"
        ]
      },
      "EmailObject": {
        "type": "object",
        "description": "Detailed email metadata object.",
        "additionalProperties": false,
        "properties": {
          "from": {
            "$ref": "#/components/schemas/EmailAddress"
          },
          "to": {
            "type": "array",
            "description": "Primary recipients.",
            "maxItems": 50,
            "items": {
              "$ref": "#/components/schemas/EmailAddress"
            }
          },
          "cc": {
            "type": "array",
            "description": "Carbon copy recipients.",
            "maxItems": 50,
            "items": {
              "$ref": "#/components/schemas/EmailAddress"
            }
          },
          "bcc": {
            "type": "array",
            "description": "Blind carbon copy recipients.",
            "maxItems": 50,
            "items": {
              "$ref": "#/components/schemas/EmailAddress"
            }
          },
          "subject": {
            "type": "string",
            "description": "The subject of the email.",
            "maxLength": 500
          },
          "content": {
            "type": "string",
            "description": "The email body content.",
            "maxLength": 32000
          },
          "mail_format": {
            "type": "string",
            "description": "Email content format.",
            "enum": [
              "text",
              "html"
            ],
            "default": "text"
          },
          "original_message_id": {
            "type": "string",
            "description": "Unique identifier from the mail server.",
            "maxLength": 255
          },
          "sent": {
            "type": "boolean",
            "description": "Whether the email was sent or received."
          },
          "date_time": {
            "type": "string",
            "format": "date-time",
            "description": "Timestamp of the email.",
            "maxLength": 50
          },
          "attachments": {
            "type": "array",
            "description": "List of associated attachments.",
            "maxItems": 20,
            "items": {
              "$ref": "#/components/schemas/AttachmentRef"
            }
          }
        },
        "required": [
          "from",
          "to",
          "subject",
          "content",
          "original_message_id",
          "sent",
          "date_time"
        ]
      },
      "EmailAddress": {
        "type": "object",
        "description": "Object representing an email address and display name.",
        "additionalProperties": false,
        "properties": {
          "user_name": {
            "type": "string",
            "description": "The display name of the user.",
            "maxLength": 255
          },
          "email": {
            "type": "string",
            "format": "email",
            "description": "The actual email address string.",
            "maxLength": 255
          }
        },
        "required": [
          "email"
        ]
      },
      "AttachmentRef": {
        "type": "object",
        "description": "Reference to an email attachment.",
        "additionalProperties": false,
        "properties": {
          "id": {
            "type": "string",
            "description": "The attachment ID.",
            "maxLength": 100
          }
        },
        "required": [
          "id"
        ]
      },
      "ActionResponse": {
        "type": "object",
        "description": "Generic wrapper for multiple record action responses.",
        "additionalProperties": false,
        "properties": {
          "data": {
            "type": "array",
            "description": "Array of result statuses.",
            "maxItems": 50,
            "items": {
              "type": "object",
              "description": "Individual result for a specific record.",
              "additionalProperties": false,
              "properties": {
                "code": {
                  "type": "string",
                  "description": "Status code.",
                  "maxLength": 50
                },
                "details": {
                  "type": "object",
                  "description": "Contextual details.",
                  "additionalProperties": false
                },
                "message": {
                  "type": "string",
                  "description": "Result message.",
                  "maxLength": 255
                },
                "status": {
                  "type": "string",
                  "description": "Operation status.",
                  "maxLength": 50
                }
              }
            }
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "description": "Details about a failed API request.",
        "additionalProperties": false,
        "properties": {
          "code": {
            "type": "string",
            "description": "Error code.",
            "maxLength": 50
          },
          "message": {
            "type": "string",
            "description": "Error message.",
            "maxLength": 255
          },
          "status": {
            "type": "string",
            "description": "Error status.",
            "maxLength": 50
          },
          "details": {
            "type": "object",
            "description": "Detailed error context.",
            "additionalProperties": false
          }
        }
      }
    },
    "securitySchemes": {
      "iam-oauth2-schema": {
        "type": "oauth2",
        "description": "Zoho CRM OAuth2 Authentication.",
        "flows": {
          "authorizationCode": {
            "authorizationUrl": "https://accounts.zoho.com/oauth/v2/auth",
            "tokenUrl": "https://accounts.zoho.com/oauth/v2/token",
            "scopes": {
              "ZohoCRM.modules.emails.CREATE": "Create email associations",
              "ZohoCRM.modules.emails.READ": "Read email associations",
              "ZohoCRM.modules.emails.ALL": "Full access to emails"
            }
          }
        }
      }
    }
  }
}