API specification for MailMerge. Published by Zoho in its first-party OpenAPI 3.1.0 repository github.com/zoho/crm-oas; 3 operation(s).
{
"openapi": "3.1.0",
"info": {
"title": "Mail Merge",
"description": "API specification for MailMerge",
"version": "8"
},
"servers": [
{
"url": "https://zohoapis.{dc}/crm/{version}",
"description": "API Server URL",
"variables": {
"dc": {
"description": "API Server URL TLD",
"default": "com",
"enum": [
"com",
"eu",
"in",
"cn",
"au",
"ca",
"jp"
]
},
"version": {
"description": "API Version",
"default": "v8"
}
}
}
],
"paths": {
"/{moduleApiName}/{recordId}/actions/send_mail_merge": {
"post": {
"summary": "POST /{module_API_name}/{recordId}/actions/send_mail_merge",
"description": "Send mail merge API to use a mail merge template and send emails to users. You can also attach files either as inline images or separate attachments with the email through the API.",
"operationId": "postSendMailMerge",
"parameters": [
{
"$ref": "#/components/parameters/ParamPathModuleApiName"
},
{
"$ref": "#/components/parameters/ParamPathRecordId"
}
],
"requestBody": {
"description": "Request body",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PostsendmailmergeRequest"
}
}
}
},
"responses": {
"200": {
"description": "OK - Successful response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PostsendmailmergeResponse200"
}
}
}
},
"400": {
"description": "Bad Request - The request cannot be processed due to invalid syntax.",
"content": {
"application/json": {
"schema": {
"description": "Error response schema for 400 status code",
"oneOf": [
{
"$ref": "#/components/schemas/InvalidModulePathError"
},
{
"$ref": "#/components/schemas/RequiredParamMissingError"
},
{
"$ref": "#/components/schemas/InvalidDataParamError"
},
{
"$ref": "#/components/schemas/InvalidRequestMethodError"
},
{
"type": "object",
"additionalProperties": false,
"description": "Wrapped error response with send_mail_merge",
"properties": {
"send_mail_merge": {
"type": "array",
"description": "Array of error objects",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/MandatoryFieldNotFoundError"
},
{
"$ref": "#/components/schemas/InvalidDataTypeError"
},
{
"$ref": "#/components/schemas/InvalidDataMaxLengthError"
}
]
},
"maxItems": 25
}
},
"required": [
"send_mail_merge"
]
}
]
}
}
}
}
},
"security": [
{
"iam-oauth2-schema": [
"ZohoCRM.settings.mailmerge.CREATE,ZohoWriter.documentEditor.ALL,ZohoWriter.merge.ALL,ZohoCRM.settings.emails.ALL"
]
}
]
}
},
"/{moduleApiName}/{recordId}/actions/sign_mail_merge": {
"post": {
"summary": "POST /{module_API_name}/{recordId}/actions/sign_mail_merge",
"description": "To send a mail merge document for signing and approval.To use this API, you must initially access the Merge and Sign dialogue from the Writer UI once. Please note that you need to do this only once.",
"operationId": "postSignMailMerge",
"parameters": [
{
"$ref": "#/components/parameters/ParamPathModuleApiName"
},
{
"$ref": "#/components/parameters/ParamPathRecordId"
}
],
"requestBody": {
"description": "Request body",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PostsignmailmergeRequest"
}
}
}
},
"responses": {
"200": {
"description": "OK - Successful response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PostsignmailmergeResponse200"
}
}
}
},
"400": {
"description": "Bad Request - The request cannot be processed due to invalid syntax.",
"content": {
"application/json": {
"schema": {
"description": "Error response schema for 400 status code",
"oneOf": [
{
"$ref": "#/components/schemas/ExpectedFieldMissingError"
},
{
"$ref": "#/components/schemas/InvalidDataParamError"
},
{
"$ref": "#/components/schemas/InvalidModulePathError"
},
{
"type": "object",
"additionalProperties": false,
"description": "Wrapped error response with sign_mail_merge",
"properties": {
"sign_mail_merge": {
"type": "array",
"description": "Array of error objects",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/MandatoryFieldNotFoundBodyError"
},
{
"$ref": "#/components/schemas/MandatoryFieldNotFoundError"
},
{
"$ref": "#/components/schemas/InvalidDataTypeError"
},
{
"$ref": "#/components/schemas/InvalidDataMaxLengthError"
}
]
},
"maxItems": 25
}
},
"required": [
"sign_mail_merge"
]
},
{
"$ref": "#/components/schemas/InvalidRequestMethodError"
}
]
}
}
}
}
},
"security": [
{
"iam-oauth2-schema": [
"ZohoCRM.settings.mailmerge.CREATE,ZohoWriter.documentEditor.ALL,ZohoWriter.merge.ALL,ZohoSign.documents.ALL"
]
}
]
}
},
"/{moduleApiName}/{recordId}/actions/download_mail_merge": {
"post": {
"summary": "POST /{module_API_name}/{recordId}/actions/download_mail_merge",
"description": "Use the download mail merge API to download the merged document created using your mail merge template.",
"operationId": "postDownloadMailMerge",
"parameters": [
{
"$ref": "#/components/parameters/ParamPathModuleApiName"
},
{
"$ref": "#/components/parameters/ParamPathRecordId"
}
],
"requestBody": {
"description": "Request body",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PostdownloadmailmergeRequest"
}
}
}
},
"responses": {
"200": {
"description": "OK - Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"description": "Response schema for download mail merge",
"properties": {
"download_mail_merge": {
"type": "array",
"description": "Array of download mail merge responses",
"items": {
"type": "object",
"additionalProperties": false,
"description": "Download mail merge response item",
"properties": {
"code": {
"type": "string",
"description": "Response code",
"maxLength": 255
},
"message": {
"type": "string",
"description": "Response message",
"maxLength": 255
},
"status": {
"type": "string",
"description": "Response status",
"maxLength": 255
}
}
},
"maxItems": 1
}
}
}
}
}
},
"400": {
"description": "Bad Request - The request cannot be processed due to invalid syntax.",
"content": {
"application/json": {
"schema": {
"description": "Error response schema for 400 status code",
"oneOf": [
{
"$ref": "#/components/schemas/ExpectedParamMissingError"
},
{
"$ref": "#/components/schemas/InvalidDataUrlError"
},
{
"$ref": "#/components/schemas/InvalidModuleParamError"
},
{
"$ref": "#/components/schemas/InvalidRequestMethodError"
},
{
"type": "object",
"additionalProperties": false,
"description": "Wrapped error response with download_mail_merge",
"properties": {
"download_mail_merge": {
"type": "array",
"description": "Array of error objects",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/MandatoryFieldNotFoundError"
},
{
"$ref": "#/components/schemas/InvalidDataTypeError"
},
{
"$ref": "#/components/schemas/InvalidDataMaxLengthError"
}
]
},
"maxItems": 25
}
},
"required": [
"download_mail_merge"
]
}
]
}
}
}
}
},
"security": [
{
"iam-oauth2-schema": [
"ZohoCRM.settings.mailmerge.CREATE,ZohoWriter.documentEditor.ALL,ZohoWriter.merge.ALL"
]
}
]
}
}
},
"components": {
"schemas": {
"InvalidDataMaxLengthError": {
"type": "object",
"additionalProperties": false,
"description": "Error when data exceeds maximum allowed length",
"properties": {
"code": {
"type": "string",
"description": "Error code",
"enum": [
"INVALID_DATA"
]
},
"details": {
"type": "object",
"additionalProperties": false,
"description": "Error details with validation information",
"properties": {
"maximum_length": {
"type": "integer",
"format": "int32",
"description": "Maximum allowed length for the field"
},
"api_name": {
"type": "string",
"description": "Name of the API field that failed validation",
"maxLength": 255
},
"json_path": {
"type": "string",
"description": "JSON path to the field that failed validation",
"maxLength": 1000
}
},
"required": [
"api_name",
"json_path",
"maximum_length"
]
},
"message": {
"type": "string",
"description": "Error message",
"enum": [
"Invalid data"
]
},
"status": {
"type": "string",
"description": "Error status",
"enum": [
"error"
]
}
},
"required": [
"code",
"details",
"message",
"status"
],
"title": "Invalid Data Max Length Error"
},
"SignMailMergeNested1": {
"type": "object",
"additionalProperties": false,
"description": "Response payload for sign mail merge operation.",
"properties": {
"code": {
"type": "string",
"description": "Response code indicating the result of the operation",
"maxLength": 255
},
"details": {
"$ref": "#/components/schemas/DetailsNested1"
},
"message": {
"type": "string",
"description": "Human-readable message describing the result",
"maxLength": 255
},
"status": {
"type": "string",
"description": "Status of the operation",
"enum": [
"success",
"error"
],
"maxLength": 255
}
}
},
"MandatoryFieldNotFoundBodyError": {
"type": "object",
"additionalProperties": false,
"description": "Error when a required field is not found in the request body",
"properties": {
"code": {
"type": "string",
"description": "Error code",
"enum": [
"MANDATORY_NOT_FOUND"
]
},
"details": {
"type": "object",
"additionalProperties": false,
"description": "Error details with validation information",
"properties": {
"api_name": {
"type": "string",
"description": "Name of the missing mandatory field",
"maxLength": 255
},
"json_path": {
"type": "string",
"description": "JSON path to the missing mandatory field",
"maxLength": 1000
}
},
"required": [
"api_name",
"json_path"
]
},
"message": {
"type": "string",
"description": "Error message",
"enum": [
"required field not found"
]
},
"status": {
"type": "string",
"description": "Error status",
"enum": [
"error"
]
}
},
"required": [
"code",
"details",
"message",
"status"
],
"title": "Mandatory Field Not Found Body Error"
},
"PostsendmailmergeResponse200": {
"type": "object",
"additionalProperties": false,
"description": "Upon successful initiation of send mail merge the response as follows.",
"properties": {
"send_mail_merge": {
"type": "array",
"description": "Field: send_mail_merge",
"items": {
"$ref": "#/components/schemas/SendMailMergeNested1"
},
"maxItems": 1
}
}
},
"DetailsNested": {
"type": "object",
"additionalProperties": false,
"description": "Response details for send mail merge operation.",
"properties": {
"report_link": {
"type": "string",
"description": "URL link to the mail merge report",
"format": "uri",
"maxLength": 255
}
}
},
"PostdownloadmailmergeRequest": {
"type": "object",
"additionalProperties": false,
"description": "Request body schema for download mail merge operation.",
"properties": {
"download_mail_merge": {
"type": "array",
"description": "Root Element (Required)",
"items": {
"$ref": "#/components/schemas/DownloadMailMergeNested"
},
"maxItems": 1
}
},
"required": [
"download_mail_merge"
]
},
"BccEmailNested": {
"type": "object",
"additionalProperties": false,
"description": "The details of the email or the mail merge field you want to include in the email's bcc. The keys are same as the ones in the \"from_address\" JSON object.",
"properties": {
"type": {
"type": "string",
"description": "Type of the address. Must be 'email'.",
"enum": [
"email"
],
"maxLength": 5
},
"value": {
"type": "string",
"format": "email",
"description": "The email ID you want to use to send emails to.",
"pattern": "^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$",
"maxLength": 255
}
},
"required": [
"type",
"value"
]
},
"MailMergeTemplateNested": {
"type": "object",
"additionalProperties": false,
"description": "Mailmerge Object to pass Template details",
"properties": {
"name": {
"type": "string",
"description": "The name of the mail merge template you want to use.",
"maxLength": 255
}
},
"required": [
"name"
]
},
"MandatoryFieldNotFoundError": {
"type": "object",
"additionalProperties": false,
"description": "Error when a required field is missing",
"properties": {
"code": {
"type": "string",
"description": "Error code",
"enum": [
"MANDATORY_NOT_FOUND"
]
},
"details": {
"type": "object",
"additionalProperties": false,
"description": "Error details with validation information",
"properties": {
"api_name": {
"type": "string",
"description": "Name of the missing mandatory field",
"maxLength": 255
},
"json_path": {
"type": "string",
"description": "JSON path to the missing mandatory field",
"maxLength": 1000
}
},
"required": [
"api_name",
"json_path"
]
},
"message": {
"type": "string",
"description": "Error message",
"enum": [
"Required field is missing"
]
},
"status": {
"type": "string",
"description": "Error status",
"enum": [
"error"
]
}
},
"required": [
"code",
"details",
"message",
"status"
],
"title": "Mandatory Field Not Found Error"
},
"InvalidDataUrlError": {
"type": "object",
"additionalProperties": false,
"description": "Error when invalid data is sent in the URL",
"properties": {
"code": {
"type": "string",
"description": "Error code",
"enum": [
"INVALID_DATA"
]
},
"details": {
"type": "object",
"additionalProperties": false,
"description": "Error details with validation information",
"properties": {
"resource_path_index": {
"type": "integer",
"format": "int32",
"description": "Index of the resource path segment that contains invalid data"
}
},
"required": [
"resource_path_index"
]
},
"message": {
"type": "string",
"description": "Error message",
"enum": [
"invalid data"
]
},
"status": {
"type": "string",
"description": "Error status",
"enum": [
"error"
]
}
},
"required": [
"code",
"details",
"message",
"status"
],
"title": "Invalid Data URL Error"
},
"InvalidModuleParamError": {
"type": "object",
"additionalProperties": false,
"description": "Error when the module given in the parameter is invalid",
"properties": {
"code": {
"type": "string",
"description": "Error code",
"enum": [
"INVALID_MODULE"
]
},
"details": {
"type": "object",
"additionalProperties": false,
"description": "Error details with validation information",
"properties": {
"param_name": {
"type": "string",
"description": "Name of the parameter containing the invalid module",
"maxLength": 255
}
},
"required": [
"param_name"
]
},
"message": {
"type": "string",
"description": "Error message",
"enum": [
"module name given seems to be invalid"
]
},
"status": {
"type": "string",
"description": "Error status",
"enum": [
"error"
]
}
},
"required": [
"code",
"details",
"message",
"status"
],
"title": "Invalid Module Param Error"
},
"SendMailMergeNested": {
"type": "object",
"additionalProperties": false,
"description": "Request payload for sending mail merge emails.",
"properties": {
"bcc_email": {
"type": "array",
"description": "The details of the email or the mail merge field you want to include in the email's bcc. The keys are same as the ones in the \"from_address\" JSON object.",
"items": {
"$ref": "#/components/schemas/BccEmailNested"
},
"maxItems": 1
},
"mail_merge_template": {
"$ref": "#/components/schemas/MailMergeTemplateNested",
"description": "Mailmerge Object to pass Template details (Required)"
},
"subject": {
"type": "string",
"description": "The subject line of the email.",
"maxLength": 255
},
"cc_email": {
"type": "array",
"description": "The details of the email or the mail merge field you want to include in the email's cc. The keys are same as the ones in the \"from_address\" JSON object.",
"items": {
"$ref": "#/components/schemas/CcEmailNested"
},
"maxItems": 1
},
"attachment_name": {
"type": "string",
"description": "The name of the attachment you want to include in the email.",
"maxLength": 255
},
"to_address": {
"type": "array",
"description": "The email ID you want to use to send emails to.",
"items": {
"$ref": "#/components/schemas/ToAddressNested"
},
"maxItems": 2
},
"type": {
"type": "string",
"description": "The attachment type you want to include in the email. The possible values are inline to send the attachment as an inline image, and attachment to send the the file separately.",
"enum": [
"inline",
"attachment"
],
"maxLength": 10
},
"message": {
"type": "string",
"description": "Represents the body or content of the email you want to send. It can include up to 100,000 characters.",
"maxLength": 100000
},
"from_address": {
"$ref": "#/components/schemas/FromAddressNested",
"description": "The email ID you want to use to send emails from. This email address must be the one of the org-verified email addresses or the current user's email ID."
}
},
"required": [
"mail_merge_template"
]
},
"ExpectedParamMissingError": {
"type": "object",
"additionalProperties": false,
"description": "Error when one of the expected parameters is missing to process the request",
"properties": {
"code": {
"type": "string",
"description": "Error code",
"enum": [
"EXPECTED_PARAM_MISSING"
]
},
"details": {
"type": "object",
"additionalProperties": false,
"description": "Error details with validation information",
"properties": {
"param_names": {
"type": "array",
"description": "List of expected parameter names, at least one of which must be provided",
"items": {
"type": "string",
"description": "Expected parameter name",
"maxLength": 255
},
"maxItems": 25
}
},
"required": [
"param_names"
]
},
"message": {
"type": "string",
"description": "Error message",
"enum": [
"One of the expected parameter is missing"
]
},
"status": {
"type": "string",
"description": "Error status",
"enum": [
"error"
]
}
},
"required": [
"code",
"details",
"message",
"status"
],
"title": "Expected Param Missing Error"
},
"RequiredParamMissingError": {
"type": "object",
"additionalProperties": false,
"description": "Error when a mandatory parameter is not given",
"properties": {
"code": {
"type": "string",
"description": "Error code",
"enum": [
"REQUIRED_PARAM_MISSING"
]
},
"details": {
"type": "object",
"additionalProperties": false,
"description": "Error details with validation information",
"properties": {
"param_name": {
"type": "string",
"description": "Name of the missing required parameter",
"maxLength": 255
}
},
"required": [
"param_name"
]
},
"message": {
"type": "string",
"description": "Error message",
"enum": [
"mandatory param missing"
]
},
"status": {
"type": "string",
"description": "Error status",
"enum": [
"error"
]
}
},
"required": [
"code",
"details",
"message",
"status"
],
"title": "Required Param Missing Error"
},
"DownloadMailMergeNested": {
"type": "object",
"additionalProperties": false,
"description": "Request payload for downloading mail merge documents.",
"properties": {
"mail_merge_template": {
"$ref": "#/components/schemas/MailMergeTemplateNested",
"description": "To pass template name (Required)"
},
"output_format": {
"type": "string",
"description": "The format you want for the document. This can be pdf, html or docx. The default format will be pdf.",
"enum": [
"pdf",
"html",
"docx"
],
"maxLength": 4
},
"file_name": {
"type": "string",
"description": "The file name you want for the document. Default value will be \"download\". Maximum size for file_name is 255 characters.",
"maxLength": 255
}
},
"required": [
"mail_merge_template"
]
},
"InvalidRequestMethodError": {
"type": "object",
"additionalProperties": false,
"description": "Error when the HTTP request method is not supported for the URL",
"properties": {
"code": {
"type": "string",
"description": "Error code",
"enum": [
"INVALID_REQUEST_METHOD"
]
},
"details": {
"type": "object",
"additionalProperties": false,
"description": "Error details with validation information",
"properties": {}
},
"message": {
"type": "string",
"description": "Error message",
"enum": [
"The http request method type is not a valid one"
]
},
"status": {
"type": "string",
"description": "Error status",
"enum": [
"error"
]
}
},
"required": [
"code",
"details",
"message",
"status"
],
"title": "Invalid Request Method Error"
},
"SignMailMergeNested": {
"type": "object",
"additionalProperties": false,
"description": "Request payload for sending documents for signature.",
"properties": {
"sign_in_order": {
"type": "boolean",
"description": "The value true indicates that the document will first be sent for approval and then for signing."
},
"signers": {
"type": "array",
"description": "The d
# --- truncated at 32 KB (48 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/zoho-crm/refs/heads/main/openapi/zoho-crm-mail-merge-openapi.json