Creates a Message Box template that displays custom messages on Windows target endpoints. The configuration is saved as a reusable template that can be deployed later. Use the returned templateId with the Deploy Configuration Template API to deploy it to targets.
post /dcapi/config-policies/v2/windows/messageBox
https://{serverurl}/dcapi/config-policies/v2/windows/messageBox Copied!
Authorization: Zoho-oauthtoken d92d4xxxxxxxxxxxxx15f52
Media type of the request body, as consumed by the endpoint.
Media type of the response body, as produced by the endpoint.
Name of the configuration. Returned as templateName in the response.
Free-text description of the configuration. May be an empty string.
What the configuration is applied to. Allowed values:
computer = applied to the endpoint
user = applied to the logged-on user
Reapply the configuration at every agent refresh, even when it has already been applied successfully.
Apply the configuration at endpoint startup when configType is computer, or at user logon when configType is user.
Apply the configuration at the scheduled agent refresh.
Retry the configuration on the endpoint when it fails. noOfRetries sets how many attempts are made.
Honour refreshMinRetry as the minimum gap between two retries at refresh.
Honour logonStartupMinRetry as the minimum gap between two retries at startup or logon.
Number of retry attempts made after a failure. Read only when enableRetry is true.
Minimum number of minutes between two retries at refresh. Read only when enableRefreshMinRetry is true.
Minimum number of minutes between two retries at startup or logon. Read only when enableLogonStartupMinRetry is true.
The message box to create or remove. Exactly one entry is expected.
Title shown in the endpoint message box. Required when msgOperation is create. For delete it identifies the message box to remove; it is ignored for deleteAll.
Message content displayed to the endpoint user. Required when msgOperation is create; ignored for delete and deleteAll.
Icon and style of the dialog. Allowed values:
info = informational icon
warning = warning icon
error = error icon
Required when msgOperation is create. Default: "info"
Seconds after which the message box closes automatically. Use 0 to keep the message box open until the user dismisses it. Default: 30
Operation to perform. Allowed values:
create = adds the message box
delete = removes the message box matching msgTitle
deleteAll = removes every message box on the endpoint
Mandatory - the request fails with HTTP 400 if omitted.
How often the message box is shown. Allowed values:
0 = at every startup (computer configType) or every logon (user configType)
1 = every time the configuration is applied
2 = a fixed number of times given by msgExecCount
3 = repeatedly until the date and time given by msgExecExpTime
Default: 1
Number of times the message box is shown. Read only when msgExecType is 2. Ignored for all other msgExecType values. Default: 0
Date and time until which the message box keeps being shown, in dd MMM yyyy, HH:mm:ss format. Mandatory when msgExecType is 3 - the request fails with HTTP 400 if omitted. Ignored for all other msgExecType values.
Send an email to the addresses listed in email once the deployment finishes.
Notify the endpoint user about this deployment. notificationDuration and notificationEnabledDays are read only when this is true.
Comma-separated email addresses notified about the deployment. May be an empty string when enableEmailNotify is false.
How long a deployment notification stays on screen for the endpoint user. Read only when enableNotification is true.
Number of days for which deployment notifications stay enabled. Read only when enableNotification is true.
curl --request POST \
--url https://appdomains/dcapi/config-policies/v2/windows/messageBox \
--header 'Accept: application/json' \
--header 'Authorization: Zoho-oauthtoken d92d4xxxxxxxxxxxxx15f52' \
--header 'Content-Type: application/json' \
--data '{"configDetails":[{"msgOperation":"create"}],"label":"Sample MESSAGE_BOX Config","configType":"computer"}'Show an informational message every time the configuration is applied. msgOperation create requires msgTitle, msgContent and msgStyle; msgExecType 1 means show every time, so msgExecCount and msgExecExpTime are ignored.
{
"applyAtRefresh": false,
"applyAlways": false,
"description": "Created through the Config Policies API.",
"label": "Sample MESSAGE_BOX Config",
"configType": "computer",
"applyAtStartupLogon": true,
"noOfRetries": 2,
"refreshMinRetry": 1,
"notificationEnabledDays": 3,
"enableLogonStartupMinRetry": false,
"logonStartupMinRetry": 1,
"configDetails": [
{
"msgContent": "Welcome to the company network",
"msgTimeout": 30,
"msgExecType": 1,
"msgTitle": "Welcome",
"msgExecExpTime": "",
"msgStyle": "info",
"msgExecCount": 1,
"msgOperation": "create"
}
],
"enableNotification": false,
"enableEmailNotify": false,
"notificationDuration": 6,
"enableRetry": false,
"enableRefreshMinRetry": false,
"email": ""
}
curl --request POST \
--url https://appdomains/dcapi/config-policies/v2/windows/messageBox \
--header 'Accept: application/json' \
--header 'Authorization: Zoho-oauthtoken d92d4xxxxxxxxxxxxx15f52' \
--header 'Content-Type: application/json' \
--data '{"configDetails":[{"msgOperation":"create"}],"label":"Warning Message Config","configType":"computer"}'Show a warning message three times and then stop. msgExecType 2 makes msgExecCount the number of times the message appears, and msgTimeout dismisses each dialog after 60 seconds.
{
"applyAtRefresh": false,
"applyAlways": false,
"description": "Created through the Config Policies API.",
"label": "Warning Message Config",
"configType": "computer",
"applyAtStartupLogon": true,
"noOfRetries": 2,
"refreshMinRetry": 1,
"notificationEnabledDays": 3,
"enableLogonStartupMinRetry": false,
"logonStartupMinRetry": 1,
"configDetails": [
{
"msgContent": "Your password will expire in 3 days",
"msgTimeout": 60,
"msgExecType": 2,
"msgTitle": "Security Warning",
"msgExecExpTime": "",
"msgStyle": "warning",
"msgExecCount": 3,
"msgOperation": "create"
}
],
"enableNotification": false,
"enableEmailNotify": false,
"notificationDuration": 6,
"enableRetry": false,
"enableRefreshMinRetry": false,
"email": ""
}
curl --request POST \
--url https://appdomains/dcapi/config-policies/v2/windows/messageBox \
--header 'Accept: application/json' \
--header 'Authorization: Zoho-oauthtoken d92d4xxxxxxxxxxxxx15f52' \
--header 'Content-Type: application/json' \
--data '{"configDetails":[{"msgOperation":"create"}],"label":"Error Alert Config","configType":"computer"}'Show an error-style dialog that stays open until the user dismisses it. msgTimeout 0 disables the auto-dismiss timer.
{
"applyAtRefresh": false,
"applyAlways": false,
"description": "Created through the Config Policies API.",
"label": "Error Alert Config",
"configType": "computer",
"applyAtStartupLogon": true,
"noOfRetries": 2,
"refreshMinRetry": 1,
"notificationEnabledDays": 3,
"enableLogonStartupMinRetry": false,
"logonStartupMinRetry": 1,
"configDetails": [
{
"msgContent": "Disk space is critically low",
"msgTimeout": 0,
"msgExecType": 1,
"msgTitle": "System Alert",
"msgExecExpTime": "",
"msgStyle": "error",
"msgExecCount": 1,
"msgOperation": "create"
}
],
"enableNotification": false,
"enableEmailNotify": false,
"notificationDuration": 6,
"enableRetry": false,
"enableRefreshMinRetry": false,
"email": ""
}
Success response returned when the configuration is saved as a reusable template.
Unique identifier of the created template. Pass it to the Deploy Configuration Template API to deploy this template to targets.
Name of the created template. It is the label sent in the request.
Type of configuration the template was created for. Allowed values:
computer
user
Login name of the API user who created the template.
Error response when the request contains invalid or missing required fields.
Product error code. 50003 = CONFIG_INVALID_INPUT_DATA: configDetails is missing or empty, or the configuration could not be resolved for this endpoint. 20003 = SERVICE_NOT_AVAILABLE: the configuration is deprecated for the requested configType.
Localised error message for the error code.
Unauthorized error code returned when authentication credentials are missing, expired, or invalid (authentication=required)
Authentication failure reason
Error response returned when the server does not have enough free disk space to store the configuration files.
Product error code. 170013 = INTERNAL_SERVER_ERROR: raised by the storage pre-check before the template is saved.
Localised error message for the error code.
Rate limit error code returned when the API call threshold (configured via threshold/duration in security XML) is exceeded; client is locked out for lock-period minutes
Rate limit exceeded message with retry guidance
Error response returned when the template could not be saved because of an unexpected server error.
Product error code. 1003 = INTERNAL_ERROR: the template could not be persisted. 50001 = CONFIG_INTERNAL_ERROR: an internal configuration error occurred while processing the request.
Localised error message for the error code.
Success response for deployMessageBox
{
"templateName": "deployMessageBox",
"templateId": 316,
"configType": "computer",
"addedUser": "admin"
}
Error response for deployMessageBox
{
"errorCode": 50003,
"errorMsg": "Some Input field missing in configuration"
}
Success response for warningMessageBox
{
"templateName": "warningMessageBox",
"templateId": 317,
"configType": "computer",
"addedUser": "admin"
}
Error response for warningMessageBox
{
"errorCode": 50003,
"errorMsg": "Some Input field missing in configuration"
}
Success response for errorMessageBox
{
"templateName": "errorMessageBox",
"templateId": 318,
"configType": "computer",
"addedUser": "admin"
}
Error response for errorMessageBox
{
"errorCode": 50003,
"errorMsg": "Some Input field missing in configuration"
}
User is not authorized to create the configuration policy
{
"errorCode": 1001,
"errorMsg": "Access denied - You are not allowed to access the requested resource."
}
Storage pre-check rejected the request before the template was saved
{
"errorCode": 170013,
"errorMsg": "The server machine does not have sufficient disk space. Please free up space and try again."
}
Request rejected because the caller exceeded the configured rate limit
{
"errorCode": "IAM0019",
"url": "/dcapi/config-policies/v2/windows/messageBox",
"errorMsg": "The URL /dcapi/config-policies/v2/windows/messageBox was called too many times. Please retry after a while."
}
Unexpected server error while saving the configuration as a template
{
"errorCode": 1003,
"errorMsg": "An Internal Error occurred, try again later."
}
![]()
Duration: 1 minute | Threshold: 30 | Lock period: 5 minutes
Duration - Time window for the threshold.
Threshold - Number of API calls allowed within the specified duration.
Lock Period - Wait time before consecutive API requests.
© 2026, Zoho Corporation Pvt. Ltd. All Rights Reserved.