openapi: 3.0.0
info:
  title: Custom Email
  description: |
    Configure a custom email address (customid@yourdomain.com) for notification emails sent from Cliq to your organisation users. Your custom email id will replace the systemgenerated@mailer.zohocliq.com email id of Cliq.
  contact: {}
  version: 1.0.0
externalDocs:
  description: Find out more about Zoho Cliq APIs V2
  url: https://www.zoho.com/cliq/help/restapi/v2/
servers:
  - url: https://cliq.zoho.com/api/v2
    description: Zoho Cliq US DC
tags:
  - name: customemail
    description: Custom Email Module
paths:
  /mailconfigurations/global:
    get:
      summary: Retrieve global mail configuration
      operationId: Retrieve global mail configuration
      description: |
        Use this API to retrieve a global mail configuration. <br><br>  <p>
          <b>Threshold limit</b>: 20 requests per min per user<br>
          Number of API calls allowed within a minute.<br><br>
          <b>Lock period</b>: 10 minutes<br>Wait time before consecutive API requests.<br>
        </p>
      responses:
        '200':
          description: The request was successfully completed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomDomainVerificationResponse'
        '400':
          description: Bad Request.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The request cannot be performed. Usually because of malformed parameter or missing parameter.
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Request was rejected because of invalid AuthToken.
        '403':
          description: Forbidden.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The user does not have enough permission or possibly not an user of the respective organization to access the resource.
        '404':
          description: Invalid URL.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The URL you've sent is wrong. It's possible that the resource you've requested has been moved to another URL.
        '405':
          description: Method Not Allowed.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The requested resource does not support the HTTP method used. For example, requesting List of all customers API with PUT as the HTTP method.
        '406':
          description: Not Acceptable.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The response has been received but the requested response type is not supported by the browser.
        '429':
          description: Too many requests.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Too many requests within a certain time frame.
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Cliq server encountered an error which prevents it from fulfilling the request.
      security:
        - Cliq_Auth:
            - ZohoCliq.Organisation.READ
      tags:
        - customemail
    delete:
      summary: Reset mail configuration
      operationId: Reset mail configuration
      description: |
        Use this API to reset the global mail configuration to system defaults. This removes any custom email address and DKIM settings that have been configured. <br><br>  <p>
          <b>Threshold limit</b>: 20 requests per min per user<br>
          Number of API calls allowed within a minute.<br><br>
          <b>Lock period</b>: 10 minutes<br>Wait time before consecutive API requests.<br>
        </p>
      responses:
        '200':
          description: The request was successfully completed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/no-response'
        '400':
          description: Bad Request.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The request cannot be performed. Usually because of malformed parameter or missing parameter.
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Request was rejected because of invalid AuthToken.
        '403':
          description: Forbidden.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The user does not have enough permission or possibly not an user of the respective organization to access the resource.
        '404':
          description: Invalid URL.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The URL you've sent is wrong. It's possible that the resource you've requested has been moved to another URL.
        '429':
          description: Too many requests.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Too many requests within a certain time frame.
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Cliq server encountered an error which prevents it from fulfilling the request.
      security:
        - Cliq_Auth:
            - ZohoCliq.Organisation.DELETE
      tags:
        - customemail
    put:
      summary: Update mail configuration
      operationId: Update mail configuration
      description: |
        Use this API to update a mail configuration. <br><br>  <p>
          <b>Threshold limit</b>: 20 requests per min per user<br>
          Number of API calls allowed within a minute.<br><br>
          <b>Lock period</b>: 10 minutes<br>Wait time before consecutive API requests.<br>
        </p>
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateEmailRequestBody'
      responses:
        '200':
          description: The request was successfully completed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomDomainVerificationResponse'
        '400':
          description: Bad Request.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The request cannot be performed. Usually because of malformed parameter or missing parameter.
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Request was rejected because of invalid AuthToken.
        '403':
          description: Forbidden.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The user does not have enough permission or possibly not an user of the respective organization to access the resource.
        '404':
          description: Invalid URL.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The URL you've sent is wrong. It's possible that the resource you've requested has been moved to another URL.
        '405':
          description: Method Not Allowed.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The requested resource does not support the HTTP method used. For example, requesting List of all customers API with PUT as the HTTP method.
        '406':
          description: Not Acceptable.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The response has been received but the requested response type is not supported by the browser.
        '429':
          description: Too many requests.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Too many requests within a certain time frame.
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Cliq server encountered an error which prevents it from fulfilling the request.
      security:
        - Cliq_Auth:
            - ZohoCliq.Organisation.UPDATE
      tags:
        - customemail
components:
  schemas:
    no-response:
      type: object
      description: Represents an empty response where no content is returned by the server.
      properties:
        Response Code:
          type: string
          description: HTTP response code indicating no content is returned.
          example: 204 No response
    CustomDomainVerificationResponse:
      type: object
      description: Response schema containing details about the verification status of a custom domain.
      properties:
        url:
          type: string
          description: The API endpoint URL of the mail configuration resource.
          example: /api/v2/mailconfigurations/global
        data:
          type: object
          description: Object containing email, DKIM, and CNAME verification details for the custom domain.
          properties:
            email_id:
              type: string
              description: Email address associated with the custom domain for verification.
              example: scott.fisher@zylkerorg.gq
            name:
              type: string
              description: Name of the custom emailer associated with the domain.
              example: Scott
            dkim_value:
              type: string
              description: Public key string used during DKIM setup, paired with a private key for domain authentication.
              example: k=rsa; p=MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQCr6KMgdxxgg7oT3ulMwPJs9RXgXDrI9UWU118pHEMohl3UbL3Jwp4oxp/9N3thh/3WCJnYV134zbEVolZwqaT3JsFEq/mQ/RpW/JnOZ3rnxqJPurb2bcfJol4SDxiWVObzHX31xnANzFcXnq1/5dMK5QvW4Jh7n0fm4+4ywqiy2QIDAQAB
            dkim_status:
              type: string
              description: Verification status of the DKIM record for the custom domain.
              enum:
                - verified
                - not_verified
              example: not_verified
            dkim_host:
              type: string
              description: Hostname used for DKIM record, to be added in the domain DNS records.
              example: 1522905413783._domainkey.zylkerorg.gq
            cname_status:
              type: string
              description: Verification status of the canonical name (CNAME) record used for domain aliasing.
              enum:
                - verified
                - not_verified
              example: verified
    UpdateEmailRequestBody:
      type: object
      description: Request body schema to update an existing custom email configuration. No field is unconditionally required - include only the fields you wish to update.
      properties:
        name:
          type: string
          description: Name of the emailer that should be updated.
          example: Scott
        email_id:
          type: string
          description: Email address associated with the emailer to be updated.
          example: scott.fisher@zylkerorg.gq
        cname_status:
          type: string
          description: Updated verification status of the CNAME record for the emailer.
          example: verified
        dkim_key_size:
          type: integer
          description: Size of the DKIM key in bits. Supported values are <code>1024</code> and <code>2048</code>.
          enum:
            - 1024
            - 2048
          example: 2048
  securitySchemes:
    Cliq_Auth:
      type: oauth2
      x-authorization-example: Bearer 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f
      flows:
        implicit:
          authorizationUrl: https://accounts.zoho.com/oauth/v2/auth
          scopes:
            ZohoCliq.Organisation.READ: Read Organization
            ZohoCliq.Organisation.UPDATE: Update Organization
            ZohoCliq.Organisation.DELETE: Delete Organization
