Client Scripts

Client Scripts are JavaScripts that are executed in a client module to automate an action based on a trigger from the client. For example, client scripts are mostly used for filling online forms where the data field displayed or auto-filling of data will be done based on an user action in the form.

Enable Client Scripts

Client Scripts will be disabled for the users in an organization by default. The administrators need to enable it for the users to start creating and using the the Client Scripts on their email client interface in Zoho Mail. Click here to learn more about enabling Client Scripts in your organization.

Only the users who are provided with the Marketplace Developer role in the organisation will be able to create client scripts in an organization.

Client Scripts in Zoho Mail

Client Script in Zoho Mail will help you create JavaScripts and execute them in the email Compose, Preview and Listing windows to automate an action based on the triggers from the email client interface.

My Scripts - These scripts are the ones that are created by the users with Marketplace developer roles in the organization to execute them in their respective email account's client interface.

Org Scripts - These scripts are the ones that are created by the users in the organization and shared to the organization for all the users to make use of the script in their email account's client interface. Once shared to the organization, these scripts should be approved by the organization administrator to have it shared to other users in the organization for them to enable and use it.

Mandatory Scripts - 

1. These scripts are the organization scripts that are marked as mandatory scripts by the script creator and approved by the Super Administrator of the organization.
2. These scripts will be automatically enabled once approved by the Super Administrator administrator and the organization users will not have an option to disable the script.
3. Only the Organization Administrators who are assigned with Marketplace Developer role will be having the permission to create and share mandatory organization scripts

Create a Client Script

1. Log in to Zoho Mail.
2. Navigate to Settings > Integrations > Developer Space > Client Scripts.
3. Click on Create New Script.
4. Provide a Name and Description for the script
5. Choose the email client module location, where the script should be executed.
   1. Mail Compose
   2. Mail Preview
   3. Mail Listing
6. Choose the trigger for the script to be executed
   1. OnSend - Available only in the Mail Compose module. The script will be executed when the Send button is clicked to send an email.
   2. OnChange - Available only in the Mail Compose module. The script will be executed based on a value update in the any of the fields of the compose window.
   3. OnLoad - Available in Mail Compose, Mail Preview, and Mail Listing modules. The script will be executed on loading any of the modules under which the script is created.
7. You can choose to Make script mandatory to mandate the script for the users in the organization upon approval by the organization administrator.
8. If the script that you create will require data fetch or push from/ to another application, a Connector should be configured for the same to execute the script.
   1. You can choose the connector by clicking on the Choose Service name option.
   2. The Connectors available in your account will be listed and you can choose the appropriate one.  
   3. You can also choose to create a new connector by clicking on the Create Connection button.
9. Edit the Code Snippet to customize the Client Script based on your requirement.
   1. If the script contains any URL to which the API call made by the script will be redirected to, a confirmation dialog will be shown for you to Trust the domain using which the API call will be made.
   2. The organization users also will be intimated of the Trusted Domain redirection when they choose to enable an Org Script for their email account.
10. Once you edit the code snippet, click Save.
    1. You can also choose to Save and Test run the script to check for correct execution.

Once saved, it will be available under the My Scripts section for you to enable and use it in your email account.

Edit a script

To edit a script already created, navigate to the My Scripts section and click on script that you want to edit. Click on the Edit icon on the top right corner. Make the necessary changes and click Save.

Delete a script

To delete a script, navigate to the My Scripts section and click on script that you want to delete. Click on the Delete icon on the top right corner. Confirm the delete action by clicking on OK on the confirmation dialogue box.

Share to Org

Once you create a script, you can choose to share it with your organization for the users in your organization to use the script in their email accounts. To share a script with your organization, navigate to  the My Scripts section and click on script that you want to share with your organization users. Click on the Share to org button.

The script will be sent for approval by the organization administrator. Once approved it will be listed under the Org Scripts section for the users to enable and use it based on their requirement.

Execution order

The script execution order will help you to sequence the order execution pattern in a module based on the triggers on the client interface. To edit the execution order of the scripts, navigate to Settings > Integrations > Developer Space > Client Scripts. Click on the Set Execution Order option. Choose the module and trigger. Click Search.

The scripts for the chosen module and trigger will be listed for you to re-order the execution order. You can drag and drop to re-order.

ZDKs available in Zoho Mail's Client Script

To show alert messages in the Mail UI

You can use the following ZDKs to display alert messages on the Mail application's UI

1. ZDK.UI.Message.Success(<content to be shown>)
2. ZDK.UI.Message.Error(<content to be shown>)
3. ZDK.UI.Message.Info(<content to be shown>)
4. ZDK.UI.Message.Warning(<content to be shown>)

For example, to display an alert message for successful validation of the email content, the ZDK should be as ZDK.UI.Message.Success("Email content validated successfully")

To fetch email content by message ID

The ZDK to fetch email content using message ID:

const messageDetails = await ZDK.UI.fetchById(messageId)

Refer to the document on Get mail details API for more details on the values returned.

To compose a new email

The ZDK to compose a new email:

ZDK.UI.Compose.createNewMail({ CONTENT: <Mail content> })

To set recipient field values (To/ Cc/ Bcc) or subject content in the email compose window (To/ Cc/ Bcc/ Subject)

To preset the recipient field values or the subject content in an email you compose use the following ZDK. 

The compose window will be launched automatically if it's not already done while the script is being executed.

ZDK.UI.Compose.setComposeFieldValues({ TO: [<set of emails to be filled>]})

For example, ZDK.UI.Compose.setComposeFieldValues({CC:[ "test1@zylker.com", "test2@zylker.com" ], subject: <Mail subject>});

To show/ hide email summary content in the email listing

Use the ZDK given below to show or hide the email summary content in the email listing:

ZDK.UI.Listing.updateMessageSummary(<messageId>, summary<true/false>);

To show a dialog box before sending an email

If you want to have a dialog box prompting you to confirm the sending of an email, you can use the ZDK given below along with a custom message of your preference:

const response = await ZDK.UI.ShowConfirmation({ text: "Are you sure want to send this email?" });

The Value of the response will be True or False based on user's action with the buttons on the dialog box. Based on the boolean value (True/ False) passed at the end of the script the email send action will be performed.

To trigger a HTTP request

const response = ZDK.HTTP.Request({
url: <api endpoint>,
method: 'POST' | 'GET' | 'PUT' | 'DELETE' | 'PATCH' | 'GET',
content,
headers,
parameters,
serviceName: "Service Name for which the connector is configured"
});

A connector should be created and authenticated for the operation that's triggered by the HTTP request. The serviceName parameter should have the connector name as the value.

The response from the API used for the connector will be the value of the response field in the script.

Sample use cases for Zoho Mail Client Scripts

Fill the reporting manager's email address in Cc based on the email address added in To field

You can use the sample script given below if you have Zoho People subscription for your organisation.

1. Create an OAuth2 Connector for Zoho People application using the scope ZOHOPEOPLE.employee.ALL
2. Provide the Service Name as People and use the same in the serviceName parameter in the script
3. Create a client script for the module location - Mail compose and trigger - On change
4. Choose the People service connector and use the code given below to write the script:

if (data.email) {
   const response = ZDK.HTTP.Request({
       url: `https://people.localzoho.com/people/api/searchbyemailIds`,
       parameters: {
           values: data.email
       },
       serviceName: "People"
   });
   const parsedResponse = JSON.parse(response.data.response)[0];
   if (parsedResponse?.reportingto) {
       ZDK.UI.Compose.setComposeFieldValues({ CC: [parsedResponse.reportingto.empEmail] });
   }
}

Click Save and compose a new email and type to Address and select it.

You will find Cc email filled with the reporting manager's email address based on the user's email address (if the user has a reporting manager mapped in Zoho People) entered in the To field.

Email content validation

Zoho Mail by default handles cases such as providing you with a warning dialog box telling that you have forgot to attach a file when the content has the phrase or term "Please find attached" or "attachment" in the email content. However using client script you can have few other validations based on your personal and organizational requirements to help you have an enhanced email experience.

For example, if you wish to have a dialog box shown to check whether you have attached a file whenever the content of the email has the term "Screenshot" in it, you can get it done using the Zoho Mail's client script.

Create a client script for the module location - Mail Compose and trigger - OnSend, and paste the code given below:

let sensitiveContent = ['screenshot'];
let isAttachmentReferred = false;
if (!composeData.hasAttachment) {
   for (let loop = 0; loop < sensitiveContent.length; loop++) {
       if (composeData.content.toLowerCase().indexOf(sensitiveContent[loop]) !== -1) {
           isAttachmentReferred = true;
       }
   }
   if (isAttachmentReferred) {
       const response = await ZDK.UI.ShowConfirmation({
           text: "You have mentioned screenshot in the mail content, but no files are attached to the email. Click confirm to proceed anyway!"
       });
       return Boolean(response);
       }
   return true;
   }
return true; 

Click Save and compose a new email with mail content having the term "screenshot" in it to check the effectiveness of the script.