OpenAPI definition for managing Email Templates APIs. Published by Zoho in its first-party OpenAPI 3.1.0 repository github.com/zoho/crm-oas; 1 operation(s).
{
"openapi": "3.1.0",
"info": {
"title": "Email Templates",
"description": "OpenAPI definition for managing Email Templates APIs.",
"version": "8.0"
},
"servers": [
{
"url": "https://zohoapis.{dc}/crm/{version}",
"description": "API Server URL",
"variables": {
"dc": {
"enum": [
"com",
"eu",
"in",
"cn",
"au"
],
"default": "com",
"description": "API Server URL TLD"
},
"version": {
"default": "v8",
"description": "API Version"
}
}
}
],
"paths": {
"/settings/email_templates": {
"get": {
"operationId": "getTemplates",
"summary": "Retrieve email templates list",
"description": "Fetches a paginated list of email templates with support for filtering, sorting, and pagination. Use page/per_page for pagination (default per_page=20, max=100), sort_by and sort_order for sorting, and filters parameter for advanced filtering.",
"parameters": [
{
"$ref": "#/components/parameters/Module"
},
{
"$ref": "#/components/parameters/SortBy"
},
{
"$ref": "#/components/parameters/SortOrder"
},
{
"$ref": "#/components/parameters/CategoryView"
},
{
"$ref": "#/components/parameters/Filters"
},
{
"$ref": "#/components/parameters/PerPage"
},
{
"$ref": "#/components/parameters/Page"
}
],
"security": [
{
"iam-oauth2-schema": [
"ZohoCRM.templates.email.READ"
]
}
],
"responses": {
"200": {
"description": "OK — list of email templates with pagination metadata",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EmailTemplatesSuccessResponse"
}
}
}
},
"204": {
"description": "No Content — no templates match the criteria"
},
"400": {
"description": "Bad Request — invalid parameters, missing mandatory fields, or invalid module",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorSingleOne"
}
}
}
}
}
}
}
},
"components": {
"schemas": {
"ModuleRef": {
"type": "object",
"description": "Reference to a module",
"properties": {
"api_name": {
"type": "string",
"maxLength": 255,
"description": "API name of the module"
},
"id": {
"type": "string",
"maxLength": 255,
"description": "Module ID"
}
},
"required": [
"api_name",
"id"
],
"additionalProperties": false
},
"FolderRef": {
"type": "object",
"description": "Reference to a folder",
"properties": {
"name": {
"type": "string",
"maxLength": 255,
"description": "Folder name"
},
"id": {
"type": "string",
"maxLength": 255,
"description": "Folder ID"
}
},
"required": [
"name",
"id"
],
"additionalProperties": false
},
"UserRef": {
"type": "object",
"description": "Reference to a user",
"properties": {
"name": {
"type": "string",
"maxLength": 255,
"description": "User name"
},
"id": {
"type": "string",
"maxLength": 255,
"description": "User ID"
}
},
"required": [
"name",
"id"
],
"additionalProperties": false
},
"MergeFieldsMetadata": {
"type": "object",
"description": "Metadata about available merge fields and variables for email templates",
"properties": {
"variables": {
"type": "object",
"description": "Variables metadata (optional)",
"additionalProperties": true
},
"modules": {
"type": "array",
"maxItems": 500,
"description": "List of modules with available merge fields",
"items": {
"$ref": "#/components/schemas/MergeModule"
}
}
},
"required": [
"variables",
"modules"
],
"additionalProperties": false
},
"MergeField": {
"type": "object",
"description": "A field available for merge in email templates",
"properties": {
"custom_field": {
"type": "boolean",
"description": "Whether this is a custom field"
},
"api_name": {
"type": "string",
"maxLength": 255,
"description": "API name of the field"
},
"id": {
"type": "string",
"maxLength": 255,
"description": "Field ID"
},
"display_name": {
"type": "string",
"maxLength": 255,
"description": "Display name of the field"
}
},
"required": [
"custom_field",
"api_name",
"id",
"display_name"
],
"additionalProperties": false
},
"MergeModule": {
"type": "object",
"description": "A module with available merge fields for email templates",
"properties": {
"api_name": {
"type": "string",
"maxLength": 255,
"description": "API name of the module"
},
"name": {
"type": "string",
"maxLength": 255,
"description": "Internal name of the module"
},
"id": {
"type": "string",
"maxLength": 255,
"description": "Module ID"
},
"display_name": {
"type": "string",
"maxLength": 255,
"description": "Display name of the module"
},
"fields": {
"type": "array",
"maxItems": 1000,
"description": "List of available merge fields in this module",
"items": {
"$ref": "#/components/schemas/MergeField"
}
},
"custom_module": {
"type": "boolean",
"description": "Whether this is a custom module"
}
},
"required": [
"api_name",
"name",
"id",
"display_name",
"fields",
"custom_module"
],
"additionalProperties": false
},
"InfoBlock": {
"type": "object",
"description": "Pagination information for the response",
"properties": {
"per_page": {
"type": "integer",
"format": "int32",
"description": "Items per page (requested or default)"
},
"page": {
"type": "integer",
"format": "int32",
"description": "Current page number"
},
"count": {
"type": "integer",
"format": "int32",
"description": "Number of items returned in `email_templates` for this response"
},
"more_records": {
"type": "boolean",
"description": "True if there are more pages available after this one"
}
},
"required": [
"per_page",
"page",
"count",
"more_records"
],
"additionalProperties": false
},
"MultiEmailTemplateItem": {
"type": "object",
"description": "Email template item in list view with summary information",
"properties": {
"created_time": {
"type": "string",
"format": "date-time",
"description": "Template creation timestamp"
},
"modified_time": {
"type": "string",
"format": "date-time",
"description": "Last modification timestamp"
},
"last_usage_time": {
"type": "string",
"format": "date-time",
"description": "Last time template was used"
},
"category": {
"type": "string",
"enum": [
"normal",
"draft"
],
"description": "Template category - normal or draft"
},
"folder": {
"$ref": "#/components/schemas/FolderRef"
},
"module": {
"$ref": "#/components/schemas/ModuleRef"
},
"created_by": {
"$ref": "#/components/schemas/UserRef"
},
"modified_by": {
"$ref": "#/components/schemas/UserRef"
},
"name": {
"type": "string",
"pattern": "^[A-Za-z0-9]{5}$",
"maxLength": 75,
"description": "Template name"
},
"id": {
"type": "string",
"maxLength": 255,
"description": "Template ID"
},
"editor_mode": {
"type": "string",
"enum": [
"plain_text",
"rich_text",
"gallery"
],
"description": "Editor mode used"
},
"favorite": {
"type": "boolean",
"description": "Whether template is marked as favorite"
},
"attachments": {
"type": "array",
"maxItems": 10,
"description": "Attachments data",
"items": {
"type": "object",
"description": "Attachment object",
"properties": {
"static_attachment": {
"type": "object",
"description": "Static attachment details",
"properties": {
"file_name": {
"type": "string",
"maxLength": 255,
"description": "Name of the file"
},
"file_id": {
"type": "string",
"maxLength": 255,
"description": "ID of the file"
}
},
"required": [
"file_name",
"file_id"
],
"additionalProperties": false
},
"id": {
"type": "string",
"maxLength": 255,
"description": "Attachment ID"
},
"type": {
"type": "string",
"maxLength": 50,
"description": "Type of attachment"
}
},
"required": [
"static_attachment",
"id",
"type"
],
"additionalProperties": false
}
},
"subject": {
"type": "string",
"maxLength": 500,
"description": "Email subject line"
},
"associated": {
"type": "boolean",
"description": "Whether template is associated with other components"
},
"active": {
"type": "boolean",
"description": "Whether template is active"
},
"consent_linked": {
"type": "boolean",
"description": "Whether consent is linked to this template"
},
"last_version_statistics": {
"type": "object",
"description": "Statistics from the last version of the template",
"properties": {
"tracked": {
"type": "integer",
"format": "int32",
"description": "Number of tracked emails sent"
},
"delivered": {
"type": "integer",
"format": "int32",
"description": "Number of delivered emails"
},
"opened": {
"type": "integer",
"format": "int32",
"description": "Number of opened emails"
},
"bounced": {
"type": "integer",
"format": "int32",
"description": "Number of bounced emails"
},
"sent": {
"type": "integer",
"format": "int32",
"description": "Number of sent emails"
},
"clicked": {
"type": "integer",
"format": "int32",
"description": "Number of link clicks"
}
},
"required": [
"tracked",
"delivered",
"opened",
"bounced",
"sent",
"clicked"
],
"additionalProperties": false
}
},
"required": [
"created_time",
"modified_time",
"last_usage_time",
"category",
"folder",
"module",
"created_by",
"modified_by",
"name",
"id",
"editor_mode",
"favorite",
"attachments",
"subject",
"associated",
"active",
"consent_linked",
"last_version_statistics"
],
"additionalProperties": false
},
"EmailTemplatesSuccessResponse": {
"type": "object",
"description": "Successful response for email templates retrieval",
"properties": {
"merge_fields_metadata": {
"$ref": "#/components/schemas/MergeFieldsMetadata"
},
"email_templates": {
"type": "array",
"maxItems": 100,
"description": "List of email templates",
"items": {
"$ref": "#/components/schemas/MultiEmailTemplateItem"
}
},
"info": {
"$ref": "#/components/schemas/InfoBlock"
}
},
"required": [
"email_templates",
"info"
],
"additionalProperties": false
},
"ErrorSingleOne": {
"description": "Single error item - can be one of multiple error types",
"oneOf": [
{
"$ref": "#/components/schemas/ErrorItemMandatoryNotFoundForGet"
},
{
"$ref": "#/components/schemas/ErrorItemInvalidDataForGet"
},
{
"$ref": "#/components/schemas/ErrorItemPatternNotMatchedForGet"
},
{
"$ref": "#/components/schemas/ErrorItemInvalidRequest"
}
]
},
"ErrorItemMandatoryNotFoundForGet": {
"description": "Error for missing mandatory fields",
"oneOf": [
{
"$ref": "#/components/schemas/ErrorItemBase"
},
{
"type": "object",
"description": "Mandatory not found error details",
"properties": {
"code": {
"type": "string",
"enum": [
"MANDATORY_NOT_FOUND"
],
"description": "Error code for missing mandatory field"
},
"details": {
"oneOf": [
{
"type": "object",
"description": "Details of missing field",
"additionalProperties": true
},
{
"type": "object",
"description": "Details with parent API name",
"properties": {
"parent_api_name": {
"type": "string",
"maxLength": 255,
"description": "API name of the parent module"
}
},
"required": [
"parent_api_name"
],
"additionalProperties": false
}
]
}
},
"additionalProperties": false
}
]
},
"ErrorItemMandatoryNotFound": {
"description": "Error item for missing mandatory field",
"allOf": [
{
"$ref": "#/components/schemas/ErrorItemBase"
},
{
"description": "Specialized properties for MANDATORY_NOT_FOUND error",
"type": "object",
"additionalProperties": false,
"properties": {
"code": {
"description": "Error code",
"type": "string",
"enum": [
"MANDATORY_NOT_FOUND"
]
},
"details": {
"oneOf": [
{
"type": "object",
"description": "Additional details",
"additionalProperties": true
},
{
"type": "object",
"description": "Details with parent API name",
"additionalProperties": false,
"properties": {
"parent_api_name": {
"description": "Parent API name",
"type": "string",
"maxLength": 128
}
},
"required": [
"parent_api_name"
]
}
]
}
}
}
]
},
"ErrorItemInvalidDataForGet": {
"description": "Error for invalid data or module",
"allOf": [
{
"$ref": "#/components/schemas/ErrorItemBase"
},
{
"type": "object",
"description": "Invalid data error details",
"properties": {
"code": {
"type": "string",
"enum": [
"INVALID_DATA",
"INVALID_MODULE"
],
"description": "Error code for invalid data or module"
},
"details": {
"type": "object",
"description": "Additional details about the invalid data",
"additionalProperties": true
}
},
"additionalProperties": false
}
]
},
"ErrorItemInvalidData": {
"description": "Error item for invalid data/module",
"allOf": [
{
"$ref": "#/components/schemas/ErrorItemBase"
},
{
"description": "Specialized properties for INVALID_DATA/INVALID_MODULE error",
"type": "object",
"additionalProperties": false,
"properties": {
"code": {
"description": "Error code",
"type": "string",
"enum": [
"INVALID_DATA",
"INVALID_MODULE"
]
},
"details": {
"description": "Additional details",
"type": "object",
"additionalProperties": true
}
}
}
]
},
"ErrorItemBase": {
"description": "Base structure for error items",
"type": "object",
"additionalProperties": false,
"properties": {
"code": {
"description": "Error code identifier",
"type": "string",
"maxLength": 128
},
"message": {
"description": "Human-readable error message",
"type": "string",
"maxLength": 1024
},
"status": {
"description": "Error severity",
"type": "string",
"enum": [
"error",
"warning",
"info"
]
},
"details": {
"description": "Additional error details",
"type": "object",
"additionalProperties": true
}
},
"required": [
"code",
"message",
"status",
"details"
]
},
"ErrorItemPatternNotMatchedForGet": {
"description": "Error for pattern validation failure",
"allOf": [
{
"$ref": "#/components/schemas/ErrorItemBase"
},
{
"type": "object",
"description": "Pattern not matched error details",
"properties": {
"code": {
"type": "string",
"enum": [
"PATTERN_NOT_MATCHED"
],
"description": "Error code for pattern mismatch"
},
"details": {
"oneOf": [
{
"type": "object",
"description": "Details with API name",
"properties": {
"api_name": {
"type": "string",
"maxLength": 255,
"description": "Field API name that failed pattern matching"
}
},
"required": [
"api_name"
],
"additionalProperties": false
},
{
"type": "object",
"description": "Generic pattern mismatch details",
"additionalProperties": true
}
]
}
},
"additionalProperties": false
}
]
},
"ErrorItemPatternNotMatched": {
"description": "Error item when a value fails to match a required pattern",
"allOf": [
{
"$ref": "#/components/schemas/ErrorItemBase"
},
{
"description": "Specialized properties for PATTERN_NOT_MATCHED error",
"type": "object",
"additionalProperties": false,
"properties": {
"code": {
"description": "Error code",
"type": "string",
"enum": [
"PATTERN_NOT_MATCHED"
]
},
"details": {
"oneOf": [
{
"type": "object",
"description": "Details with api name",
"additionalProperties": false,
"properties": {
"api_name": {
"description": "API name that failed pattern",
"type": "string",
"maxLength": 128
}
},
"required": [
"api_name"
]
},
{
"type": "object",
"description": "Additional details",
"additionalProperties": true
}
]
}
}
}
]
},
"ErrorItemInvalidRequest": {
"description": "Error item for invalid request payloads",
"type": "object",
"additionalProperties": false,
"properties": {
"status": {
"description": "Error status",
"type": "string",
"enum": [
"error"
]
},
"code": {
"description": "Error code",
"type": "string",
"enum": [
"INVALID_REQUEST",
"JSON_PARSE_ERROR",
"INVALID_MODULE"
]
},
"message": {
"description": "Error message",
"type": "string",
"maxLength": 1024
},
"details": {
"description": "Additional details",
"type": "object",
"additionalProperties": true
}
},
"required": [
"status",
"code",
"message",
"details"
]
}
},
"parameters": {
"Module": {
"name": "module",
"in": "query",
"required": false,
"description": "Module API name for filtering",
"schema": {
"type": "string",
"maxLength": 255
}
},
"Filters": {
"name": "filters",
"in": "query",
"required": false,
"schema": {
"type": "string",
"maxLength": 10000
},
"description": "JSON-stringified filter expression. See operation description for supported comparators and group_operator."
},
"SortBy": {
"name": "sort_by",
"in": "query",
"required": false,
"description": "Field name to sort by",
"schema": {
"type": "string",
"maxLength": 255
}
},
"SortOrder": {
"name": "sort_order",
"in": "query",
"required": false,
"description": "Sort order (ascending or descending)",
"schema": {
"type": "string",
"enum": [
"asc",
"desc"
],
"default": "desc"
}
},
"PerPage": {
"name": "per_page",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"format": "int32",
"default": 20,
"minimum": 1,
"maximum": 100
},
"description": "Number of items per page (default = 20, max = 100)"
},
"Page": {
"name": "page",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"format": "int32",
"default": 1,
"minimum": 1
},
"description": "Page number, starting at 1"
},
"CategoryView": {
"description": "Template category filter. Note: Allowed values are favorite | created_by_me | shared_with_me | associated | draft.",
"name": "category",
"in": "query",
"required": false,
"schema": {
"type": "string",
"maxLength": 64,
"pattern": "^(favorite|created_by_me|shared_with_me|associated|draft)$"
}
}
},
"securitySchemes": {
"iam-oauth2-schema": {
"type": "oauth2",
"flows": {
"authorizationCode": {
"authorizationUrl": "https://accounts.zoho.com/oauth/v2/auth",
"tokenUrl": "https://accounts.zoho.com/oauth/v2/token",
"refreshUrl": "https://accounts.zoho.com/oauth/v2/token",
"scopes": {
"ZohoCRM.templates.email.CREATE": "Create email templates.",
"ZohoCRM.templates.email.READ": "Read email templates.",
"ZohoCRM.templates.email.UPDATE": "Update email templates.",
"ZohoCRM.templates.email.DELETE": "Delete email templates.",
"ZohoCRM.templates.email.send_test_mail.CREATE": "Send test mail for email templates."
}
}
}
}
}
}
}