Zoho Email Drafts API

openapi: 3.2.0
info:
  title: Helpcenter Email Drafts API
  version: 1.0.0
tags:
- name: Email Drafts
paths:
  /{module}/{record}/__email_drafts:
    get:
      summary: Get email drafts for a record
      description: Retrieves the list of email drafts associated with the specified record in the given module.
      operationId: getEmailDrafts
      parameters:
      - name: module
        in: path
        required: true
        schema:
          type: string
          maxLength: 100
        description: module of the record
      - name: record
        in: path
        required: true
        schema:
          type: string
          maxLength: 100
        description: Entity id of the record
      - $ref: '#/components/parameters/Page'
      - $ref: '#/components/parameters/PerPage'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                description: Response containing the list of email drafts and additional info (e.g., pagination).
                additionalProperties: false
                properties:
                  __email_drafts:
                    type: array
                    description: List of email draft objects.
                    maxItems: 100
                    items:
                      type: object
                      description: Email draft object with metadata, recipients and attachments.
                      additionalProperties: false
                      properties:
                        id:
                          type: string
                          description: Unique draft identifier.
                          maxLength: 64
                        modified_time:
                          type: string
                          format: date-time
                          description: Timestamp when the draft was last modified.
                        created_time:
                          type: string
                          format: date-time
                          description: Timestamp when the draft was created.
                        from:
                          type: string
                          pattern: ^[a-z]{7}@zoho\.com$
                          description: Sender email address.
                          maxLength: 100
                        to:
                          type: array
                          description: Primary recipients for the draft.
                          maxItems: 100
                          items:
                            type: object
                            description: Recipient object.
                            additionalProperties: false
                            properties:
                              user_name:
                                type: string
                                description: Recipient display name.
                                maxLength: 100
                              email:
                                type: string
                                pattern: ^[a-z]{7}@zoho\.com$
                                description: Recipient email address.
                                maxLength: 100
                            required:
                            - user_name
                            - email
                        reply_to:
                          type:
                          - string
                          - 'null'
                          pattern: ^[a-z]{7}@zoho\.com$
                          description: Reply-to email address.
                          maxLength: 100
                        cc:
                          type: array
                          description: CC recipients for the draft.
                          maxItems: 100
                          items:
                            type: object
                            description: CC recipient object.
                            additionalProperties: false
                            properties:
                              user_name:
                                type: string
                                description: CC recipient display name.
                                maxLength: 100
                              email:
                                type: string
                                pattern: ^[a-z]{7}@zoho\.com$
                                description: CC recipient email address.
                                maxLength: 100
                            required:
                            - user_name
                            - email
                        bcc:
                          type: array
                          description: BCC recipients for the draft.
                          maxItems: 100
                          items:
                            type: object
                            description: BCC recipient object.
                            additionalProperties: false
                            properties:
                              user_name:
                                type: string
                                description: BCC recipient display name.
                                maxLength: 100
                              email:
                                type: string
                                pattern: ^[a-z]{7}@zoho\.com$
                                description: BCC recipient email address.
                                maxLength: 100
                            required:
                            - user_name
                            - email
                        $sharing_permission:
                          type: string
                          description: Sharing permission level for the draft.
                          maxLength: 64
                        inventory_details:
                          type: object
                          description: Inventory related details for the draft.
                          additionalProperties: false
                          properties:
                            inventory_template:
                              type: object
                              description: Inventory template details.
                              additionalProperties: false
                              properties:
                                name:
                                  type: string
                                  description: Inventory template name.
                                  maxLength: 100
                                id:
                                  type: string
                                  description: Inventory template identifier.
                                  maxLength: 100
                              required:
                              - name
                              - id
                            paper_type:
                              type: string
                              enum:
                              - A4
                              - USLetter
                              description: Paper type for rendered inventory.
                            view_type:
                              type: string
                              enum:
                              - portrait
                              - landscape
                              description: Layout/view type for the inventory.
                          required:
                          - inventory_template
                          - paper_type
                          - view_type
                        attachments:
                          type: array
                          description: Attachments included with the draft.
                          maxItems: 10
                          items:
                            type: object
                            description: Attachment metadata.
                            additionalProperties: false
                            properties:
                              service_name:
                                type: string
                                description: Name of the storage/service holding the file.
                                maxLength: 100
                              file_size:
                                type: string
                                pattern: ^[0-9]+$
                                description: File size in bytes (string).
                                maxLength: 20
                              id:
                                type: string
                                description: Attachment identifier.
                                maxLength: 64
                              file_name:
                                type: string
                                description: Original file name.
                                maxLength: 255
                            required:
                            - service_name
                            - file_size
                            - id
                            - file_name
                        schedule_details:
                          type: object
                          description: Scheduling information for when the draft should be sent.
                          additionalProperties: false
                          properties:
                            time:
                              type: string
                              format: date-time
                              description: Scheduled send time.
                            timezone:
                              type:
                              - object
                              - 'null'
                              description: Timezone information or null.
                            source:
                              type: string
                              enum:
                              - ecOneHourAhead
                              - upTime
                              - ecSchduleBestTime
                              - ecUpComing
                              - ecSchduleTime
                              description: Source of the schedule decision.
                              default: upTime
                          required:
                          - time
                          - timezone
                          - source
                        rich_text:
                          type: boolean
                          description: Indicates whether the content is rich text.
                        subject:
                          type:
                          - string
                          - 'null'
                          description: Email subject.
                          maxLength: 512
                        content:
                          type:
                          - string
                          - 'null'
                          description: Email content/HTML/plain text.
                        summary:
                          type:
                          - string
                          - 'null'
                          description: Short summary or preview of the draft.
                        owner:
                          type: object
                          description: Owner/user who created the draft.
                          additionalProperties: false
                          properties:
                            name:
                              type: string
                              description: Owner display name.
                              maxLength: 100
                            id:
                              type: string
                              description: Owner identifier.
                              maxLength: 64
                          required:
                          - name
                          - id
                      required:
                      - id
                      - modified_time
                      - created_time
                      - from
                      - to
                      - reply_to
                      - cc
                      - bcc
                      - $sharing_permission
                      - inventory_details
                      - attachments
                      - schedule_details
                      - rich_text
                      - subject
                      - content
                      - summary
                      - owner
                  info:
                    type: object
                    description: Additional response info (pagination, cursors, etc.).
                    additionalProperties: false
                required:
                - __email_drafts
                - info
        '204':
          description: when the response is empty
        '400':
          description: Bad Request - The request could not be processed due to invalid input or parameters.
          content:
            application/json:
              schema:
                oneOf:
                - type: object
                  description: Generic error response object.
                  additionalProperties: true
      security:
      - iam-oauth2-schema:
        - ZohoCRM.modules.leads.READ
      - iam-oauth2-schema:
        - ZohoCRM.modules.accounts.READ
      - iam-oauth2-schema:
        - ZohoCRM.modules.contacts.READ
      - iam-oauth2-schema:
        - ZohoCRM.modules.deals.READ
      - iam-oauth2-schema:
        - ZohoCRM.modules.quotes.READ
      - iam-oauth2-schema:
        - ZohoCRM.modules.salesorders.READ
      - iam-oauth2-schema:
        - ZohoCRM.modules.purchaseorders.READ
      - iam-oauth2-schema:
        - ZohoCRM.modules.custom.READ
      - iam-oauth2-schema:
        - ZohoCRM.modules.cases.READ
      tags:
      - Email Drafts
    post:
      summary: Create email drafts for a record
      description: Creates one or more email drafts associated with the specified record in the given module.
      operationId: createEmailDrafts
      parameters:
      - name: module
        in: path
        required: true
        schema:
          type: string
          maxLength: 100
        description: module of the record
      - name: record
        in: path
        required: true
        description: Entity id of the record
        schema:
          type: string
          maxLength: 100
      requestBody:
        content:
          application/json:
            schema:
              type: object
              description: Request body for creating email drafts.
              additionalProperties: false
              properties:
                __email_drafts:
                  type: array
                  description: List of email drafts to create.
                  maxItems: 100
                  items:
                    type: object
                    description: Email draft object.
                    additionalProperties: false
                    properties:
                      from:
                        type: string
                        description: Sender email address.
                        pattern: ^[a-z]{7}@zoho\.com$
                        maxLength: 100
                      to:
                        type: array
                        description: List of recipients.
                        maxItems: 100
                        items:
                          type: object
                          description: Recipient object.
                          additionalProperties: false
                          properties:
                            user_name:
                              type: string
                              description: Recipient user name.
                              maxLength: 100
                            email:
                              type: string
                              description: Recipient email address.
                              pattern: ^[a-z]{7}@zoho\.com$
                              maxLength: 100
                      reply_to:
                        type: string
                        description: Reply-to email address.
                        pattern: ^[a-z]{7}@zoho\.com$
                        maxLength: 100
                      cc:
                        type: array
                        description: List of CC recipients.
                        maxItems: 100
                        items:
                          type: object
                          description: CC recipient object.
                          additionalProperties: false
                          properties:
                            user_name:
                              type: string
                              description: CC recipient user name.
                              maxLength: 100
                            email:
                              type: string
                              description: CC recipient email address.
                              pattern: ^[a-z]{7}@zoho\.com$
                              maxLength: 100
                      bcc:
                        type: array
                        description: List of BCC recipients.
                        maxItems: 100
                        items:
                          type: object
                          description: BCC recipient object.
                          additionalProperties: false
                          properties:
                            user_name:
                              type: string
                              description: BCC recipient user name.
                              maxLength: 100
                            email:
                              type: string
                              description: BCC recipient email address.
                              pattern: ^[a-z]{7}@zoho\.com$
                              maxLength: 100
                      inventory_details:
                        type: object
                        description: Inventory details for the email draft.
                        additionalProperties: false
                        properties:
                          inventory_template:
                            type: object
                            description: Inventory template details.
                            additionalProperties: false
                            properties:
                              id:
                                type: string
                                description: Inventory template ID.
                                maxLength: 100
                            required:
                            - id
                          paper_type:
                            type: string
                            description: Paper type.
                            enum:
                            - A4
                            - USLetter
                          view_type:
                            type: string
                            description: View type.
                            enum:
                            - portrait
                            - landscape
                        required:
                        - inventory_template
                        - paper_type
                        - view_type
                      schedule_details:
                        type: object
                        description: Schedule details for the email draft.
                        additionalProperties: false
                        properties:
                          time:
                            type: string
                            description: Scheduled time.
                            format: date-time
                          timezone:
                            type:
                            - object
                            - 'null'
                            description: Timezone for the scheduled time.
                          source:
                            type:
                            - string
                            - 'null'
                            description: Source of the schedule.
                            enum:
                            - ecOneHourAhead
                            - upTime
                            - ecSchduleBestTime
                            - ecUpComing
                            - ecSchduleTime
                            default: upTime
                        required:
                        - time
                      rich_text:
                        type: boolean
                        description: Whether the email content is rich text.
                      subject:
                        type:
                        - string
                        - 'null'
                        description: Subject of the email.
                        maxLength: 512
                      content:
                        type:
                        - string
                        - 'null'
                        description: Content of the email.
                    required:
                    - from
                    - rich_text
                info:
                  type: object
                  description: Additional info for the request.
                  additionalProperties: false
              required:
              - __email_drafts
        required: true
      responses:
        '201':
          description: Successful creation of email drafts.
          content:
            application/json:
              schema:
                type: object
                description: Response object containing the result of created email drafts.
                additionalProperties: false
                properties:
                  __email_drafts:
                    type: array
                    description: List of created email draft results.
                    maxItems: 100
                    items:
                      type: object
                      description: Result of a single created email draft.
                      additionalProperties: false
                      properties:
                        code:
                          type: string
                          enum:
                          - SUCCESS
                          description: Status code for the operation.
                        message:
                          type: string
                          description: Operation message.
                          maxLength: 512
                        status:
                          type: string
                          enum:
                          - success
                          description: Status of the operation.
                        details:
                          type: object
                          description: Details of the created draft.
                          additionalProperties: false
                          properties:
                            id:
                              type: string
                              description: ID of the created draft.
                              maxLength: 64
                          required:
                          - id
                      required:
                      - code
                      - message
                      - status
                      - details
                required:
                - __email_drafts
        '400':
          description: Bad Request - The request could not be processed due to invalid input or parameters.
          content:
            application/json:
              schema:
                anyOf:
                - type: object
                  description: Invalid request format
                  additionalProperties: true
                - type: object
                  description: Invalid module
                  additionalProperties: true
                - type: object
                  description: Invalid record
                  additionalProperties: true
                - type: object
                  description: Invalid draft
                  additionalProperties: true
                - type: object
                  description: Validation error response
                  additionalProperties: true
                  properties:
                    __email_drafts:
                      type: array
                      description: Email drafts validation errors
                      items:
                        type: object
                        description: Validation error details
                        additionalProperties: true
                      maxItems: 100
                  required:
                  - __email_drafts
                - type: object
                  description: Missing required fields error
                  additionalProperties: true
                  properties:
                    __email_drafts:
                      type: array
                      description: Email drafts errors
                      items:
                        type: object
                        description: Error details
                        additionalProperties: true
                      maxItems: 100
                  required:
                  - __email_drafts
                - type: object
                  description: Invalid field values error
                  additionalProperties: true
                  properties:
                    __email_drafts:
                      type: array
                      description: Email drafts with invalid values
                      items:
                        type: object
                        description: Invalid field error
                        additionalProperties: true
                      maxItems: 100
                  required:
                  - __email_drafts
                - type: object
                  description: Invalid email format error
                  additionalProperties: true
                  properties:
                    __email_drafts:
                      type: array
                      description: Email drafts with invalid email addresses
                      items:
                        type: object
                        description: Email format error
                        additionalProperties: true
                      maxItems: 100
                  required:
                  - __email_drafts
        '403':
          description: Forbidden - the user does not have permission to perform the operation.
          content:
            application/json:
              schema:
                type: object
                description: Permission error response returned when the caller lacks required permissions.
                additionalProperties: false
                properties:
                  code:
                    type: string
                    enum:
                    - NO_PERMISSION
                    description: Error code identifying the permission error.
                  message:
                    type: string
                    maxLength: 512
                    description: Human-readable message describing the permission error.
                  status:
                    type: string
                    enum:
                    - error
                    description: High-level status of the response.
                  details:
                    type: object
                    additionalProperties: true
                    description: Optional object containing additional details about the error.
                required:
                - code
                - message
                - status
                - details
      security:
      - iam-oauth2-schema:
        - ZohoCRM.modules.leads.CREATE
      - iam-oauth2-schema:
        - ZohoCRM.modules.accounts.CREATE
      - iam-oauth2-schema:
        - ZohoCRM.modules.contacts.CREATE
      - iam-oauth2-schema:
        - ZohoCRM.modules.deals.CREATE
      - iam-oauth2-schema:
        - ZohoCRM.modules.quotes.CREATE
      - iam-oauth2-schema:
        - ZohoCRM.modules.salesorders.CREATE
      - iam-oauth2-schema:
        - ZohoCRM.modules.purchaseorders.CREATE
      - iam-oauth2-schema:
        - ZohoCRM.modules.custom.CREATE
      - iam-oauth2-schema:
        - ZohoCRM.modules.cases.CREATE
      tags:
      - Email Drafts
  /{module}/{record}/__email_drafts/{draft}:
    get:
      summary: Get email draft
      description: Retrieves the specified email draft for the given record in the module.
      operationId: getEmailDraft
      parameters:
      - $ref: '#/components/parameters/Module'
      - $ref: '#/components/parameters/Record'
      - $ref: '#/components/parameters/Draft'
      responses:
        '200':
          description: When there is no drafts to show
          content:
            application/json:
              schema:
                type: object
                description: Response containing the list of email drafts and additional info (e.g., pagination).
                additionalProperties: false
                properties:
                  __email_drafts:
                    type: array
                    description: List of email draft objects.
                    maxItems: 100
                    items:
                      type: object
                      description: Email draft object with metadata, recipients and attachments.
                      additionalProperties: false
                      properties:
                        id:
                          type: string
                          description: Unique draft identifier.
                          maxLength: 64
                        modified_time:
                          type: string
                          format: date-time
                          description: Timestamp when the draft was last modified.
                        created_time:
                          type: string
                          format: date-time
                          description: Timestamp when the draft was created.
                        from:
                          type: string
                          pattern: ^[a-z]{7}@zoho\.com$
                          description: Sender email address.
                          maxLength: 100
                        to:
                          type: array
                          description: Primary recipients for the draft.
                          maxItems: 100
                          items:
                            type: object
                            description: Recipient object.
                            additionalProperties: false
                            properties:
                              user_name:
                                type:
                                - string
                                - 'null'
                                description: Recipient display name.
                                maxLength: 100
                              email:
                                type: string
                                pattern: ^[a-z]{7}@zoho\.com$
                                description: Recipient email address.
                                maxLength: 100
                            required:
                            - user_name
                            - email
                        reply_to:
                          type:
                          - string
                          - 'null'
                          pattern: ^[a-z]{7}@zoho\.com$
                          description: Reply-to email address.
                          maxLength: 100
                        cc:
                          type: array
                          description: CC recipients for the draft.
                          maxItems: 100
                          items:
                            type: object
                            description: CC recipient object.
                            additionalProperties: false
                            properties:
                              user_name:
                                type:
                                - string
                                - 'null'
                                description: CC recipient display name.
                                maxLength: 100
                              email:
                                type: string
                                pattern: ^[a-z]{7}@zoho\.com$
                                description: CC recipient email address.
                                maxLength: 100
                            required:
                            - user_name
                            - email
                        bcc:
                      

# --- truncated at 32 KB (58 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/zoho/refs/heads/main/openapi/zoho-email-drafts-api-openapi.yml