Update Email Notification

Purpose

To update an email notifications in your Zoho CRM organization.

Endpoints

  • PUT /settings/automation/email_notifications/{email_notification_ID}

Request Details

Request URL

To update an email notifications
{api-domain}/crm/{version}/settings/automation/email_notifications/{email_notification_ID}
 

Supported modules

Leads, Accounts, Contacts, Deals, Tasks, Meetings, Calls, Products, Quotes, Sales Orders, Purchase Orders, Invoices, Campaigns, Vendors, Price Books, Cases, Solutions, and Custom

Header

Authorization: Zoho-oauthtoken d92d4xxxxxxxxxxxxx15f52

Scope

ZohoCRM.settings.automation_actions.{operation_type}

Possible operation types

ALL - Full access to email notificationsUPDATE - Update email notifications

Sample Request for updating email notifications

Copiedcurl "https://www.zohoapis.com/crm/v/settings/automation/email_notifications/6660682000001456001"
-X POST
-H "Authorization: Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"-d "@updateemailnotification.json"

Input JSON

  • feature_typestring, optional

    Represents the automation for which this action will be triggered.
    Possible values: workflow.

  • templateJSON object, optional

    Represents the name and ID of the email template.

  • moduleJSON object, optional

    Represents the API name and ID of the module.

  • related_moduleJSON object, optional

    Represents the related module of the automation. For instance, if you want to trigger the Workflow based on records notes, add the details of Notes module here. The JSON object contains the API name and the ID of the related module notes.

  • bulk_emailBoolean, optional

    Specify whether the email notification should be sent a single mass email with all the recipients displayed. When this value is set as true, you can add recipients in CC or BCC.
    Possible values: true, false. The default value is false.

  • recipientsJSON object, optional

    Represents the recipients of the email notification. This JSON object consists of three JSON arrays: to, cc and bcc.

    • toJSON array, optional

      Represents the direct recipients of the notification

    • ccJSON array, optional

      Represents the recipients that you want to cc

    • bccJSON array, optional

      Represents the recipients that you want to bcc

    The recipients can be:

    1. People associated with the record, such as the record’s primary email, secondary email, owner, creator, or the owner’s manager.
    2. If the module contains a lookup field, the recipient can be the lookup’s email, secondary email, owner, or creator.
    3. Other resources, such as groups, roles, roles and subordinates, territories, territories and sub-territories, or users.
    4. Additional custom email recipients.

    Each array element inside to/cc/bcc JSON array should contain the type key and the details object or resources object based on the type.

    • typestring, mandatory

      Indicates the type of the recipient. 

      Possible value for type:

      • merge_field (placeholder field that dynamically populate content)
      • group
      • role
      • role_and_subordinate
      • territory
      • territory_and_subterritory
      • emails
      • user (Applicable for team modules)
      • profile (Applicable for team modules)
    • associated_tostring, optional

      Indicates that the intended recipients are associated to team module. The intended recipients are team module profiles or team module users. 
      Possible types: team_modules.
      Note that this value is should not be provided in other cases.

    • detailsobject, mandatory when type is merge_field or emails.

      Specifies the merge field used to dynamically resolve the recipient’s email address.
      This should be given only when type is merge_field or emails.

      • api_namestring, mandatory when type is merge_field.

        Specifies merge field API name to resolve the email address dynamically.
        Example: ${!Deals.Contact_Name.Email}. This should be given only when type is merge_field.

      • idstring, optional

        The ID of the merge field. This should be given only when type is merge_field

                            {
                                "associated_to": null,
                                "resource": null,
                                "details": {
                                    "api_name": "${!Leads.Created_By}",
                                    "id": "6660682000000033043"
                                },
                                "type": "merge_field"
                            }
      • emailsJSON array, mandatory when type is emails

        The email address of additional recipients This should be given only when type is emails

                            {
                                "details": {
                                    "emails": [
                                        "saun.smith@zohotest.com",
                                        "maria.kyle@zohotest.com"
                                    ]
                                },
                                "type": "emails"
                            }
    • resourceJSON object, mandatory when type is group, role, role_and_subordinate, user, territory, and territory_and_subterritory

      Specify a user group, territories, roles or other resource to which the notification will be sent.
      Note: Should be given only when type is user, group, role, role_and_subordinate, territory or territory_and_subterritory.

      • namestring

        The name of the resource or user group.

      • idstring

        The ID of the resource.

For a quick reference, see the detailed tables for all keys, types, and example values.

Possible recipients types for to, cc and bcc

Possible recipients for type merge_field
Intended Recipientdetails.api_name
User field from the record${!{module_API_name}.{user_field_APIname}}
For example, ${!Deals.User_1}
Multi-user field from the record${!{module_API_name}.{multiuser_field_APIname}
For example, ${!Deals.Multi_User_1}
Email field accessed via a lookup field on the record${!{module_API_name}.{lookup_APIname}.{email_field_API_name}}
For example, ${!Leads.Lookup_1.Email}
The user who created the record${!{module_API_name}.Created_By}
For example, ${!Leads.Created_By}
The owner of the record${!{module_API_name}.Owner}
For example, ${!Leads.Owner}
The manager of the record owner${!{module_API_name}.Owner.Reporting_To}
For example, ${!Leads.Owner.Reporting_To}
Email field directly present on the record${!{module_API_name}.{email_field_API_name}}
For example, ${!Leads.Owner.Email_1}
Possible recipients for groups, roles and territories
Intended RecipientTyperesource.name
A predefined CRM user groupgroup{user_group_ID}
A specific CRM role onlyrole{role_ID}
A CRM role and all its subordinatesrole_and_subordinate{role_ID}
Users assigned to a specific sales territoryterritory{territory_ID}
Users assigned to a specific territory and its subterritoriesterritory_and_subterritory{territory_ID}
Users of the CRM organizationuser{user_ID}
  • Email recipients can be added by providing direct email address in the below format

    Intended RecipientTypedetails.emails
    EmailemailsEmail address of the recipient
    For example,"details": { "emails":["john.smith@zohotest.com"]}
  • For team modules, in addition to the above fields the recipient can be Groups and Roles. The "associated_to" should be given as team_module.

    Intended RecipientTyperesource.name
    A specific user in the context of a team moduleuser{user_ID}
    All users having a profile within a specific team moduleprofile{profile_ID}
                         {
                            "associated_to": "team_module",
                            "resource": {
                                "name": "Patricia Boyle",
                                "id": "6660682000000501001"
                            },
                            "details": null,
                            "type": "user"
                        },
                        {
                            "associated_to": "team_module",
                            "resource": {
                                "name": "Managers",
                                "id": "6660682000000890088"
                            },
                            "details": null,
                            "type": "profile"
                        } 
  • Calls/Meetings module: When module for which email notification is created is calls or meetings module, the merge field must be given in a specifc format.

    Intended RecipientAllowed Merge Field Format
    To people associated to the Contacts of the call/meeting
    • ${!Calls.Who_Id.Owner}
      ${!Events.Who_Id.Owner}>
    • ${!Calls.Who_Id.Created_By}
      ${!Events.Who_Id.Created_By}>
    • ${!Calls.Who_Id.Email}
      ${!Events.Who_Id.Email}>
    • ${!Calls.Who_Id.Secondary_Email}
      ${!Events.Who_Id.Secondary_Email}>
    To people associated with other modules the contact of the call/meeting is associated with.
    • ${!Calls.What_Id->{module_API_name}.Owner}
      ${!Events.What_Id->{module_API_name}.Owner}
    • ${!Calls.What_Id->{module_API_name}.Created_By}
      ${!Events.What_Id->{module_API_name}.Created_By}
    • ${!Calls.What_Id->{module_API_name}.Email}
      ${!Events.What_Id->{module_API_name}.Email}
    • ${!Calls.What_Id->{module_API_name}.Secondary_Email}
      ${!Events.What_Id->{module_API_name}.Secondary_Email}
  • name string, optional

    Name of the email notification.

  • from_address JSON object, optional

    Specify the address of the email notification will be sente.

  • reply_to_address string, optional

    Represents the email address to which the recipient will reply when they click on "Reply" for the email notification

Note

When an email is sent exclusively to users within the organization (such as the record owner, owner's manager, creator, organizational roles, groups, territories, or profiles), the "from_address" and "reply_to_address" fields cannot be specified. DEPENDENT_MISMATCH error will be thrown if it is specified.

  • Possible values for from_address and reply_to_address

    TypeValueFormatExample
    merge_fieldEmail address of the current userapi_name as ${!Current.User.Email}"reply_to_address":{"details":{"api_name":"${!Current.User.Email}"},"type":"merge_field"}
    Email address of the record ownerapi_name as ${!Record.Owner.Email}"from_address":{"details":{"api_name":"${!Record.Owner.Email}"},"type":"merge_field"}
    userOwn/Other user's email addressresource.id. 
    For example, {user.ID of the user}
    "reply_to_address":{"resource":{"id":"6660682000000501001"},"type":"user"}
    organization_emailOrganization email addressresource.id like {org_email_ID of the organization}"from_address":{"resource":{"id":"6660682000001442351"},"type":"organization_email"}

Note

  • The From address is mandatory when sending notifications as a single mass email.
  • When bulk_email is set as  false, crm users receive the email from notifications@zohocrm.com.
  • When bulk_email is set as true, the users will receive the email from the configured From address, not from notifications@zohocrm.com.
  • Roles, Groups, and Territories cannot be selected directly as recipients. Select individual users or add their email addresses under Additional Recipients.
  • Recipient limits:
    • To: Maximum 100 email addresses
    • CC: Maximum 50 email addresses
    • BCC: Maximum 50 email addresses
  • Each module can have one Multi-Select User Lookup field with up to 10 users. These users count toward the total recipient limits. For example, if 10 users are added in the Multi-Select User Lookup, only 90 more addresses can be added to the To array.
  • Consent and Survey links are not supported in bulk emails. Templates containing these links cannot be used for single mass emails.

Sample Request

Copied{
    "email_notifications": [
        {
            "from_address": {
                "resource": {
                    "id": "6660682000000501001"
                },
                "type": "user"
            },
            "recipients": {
                "to": [
                    {
                        "details": {
                            "api_name": "${!Deals.Created_By}",
                            "id": "6660682000000002577"
                        },
                        "type": "merge_field"
                    },
                    {
                        "details": {
                            "api_name": "${!Deals.Owner}",
                            "id": "6660682000000002555"
                        },
                        "type": "merge_field"
                    },
                    {
                        "details": {
                            "api_name": "${!Deals.Owner.Reporting_To}",
                            "id": "6660682000000256015"
                        },
                        "type": "merge_field"
                    },
                    {
                        "details": {
                            "api_name": "${!Deals.Campaign_Source.Owner}",
                            "id": "6660682000000002647"
                        },
                        "type": "merge_field"
                    },
                    {
                        "details": {
                            "api_name": "${!Deals.Campaign_Source.Created_By}",
                            "id": "6660682000000002669"
                        },
                        "type": "merge_field"
                    },
                    {
                        "details": {
                            "api_name": "${!Deals.Account_Name.Owner}",
                            "id": "6660682000000002421"
                        },
                        "type": "merge_field"
                    },
                    {
                        "details": {
                            "api_name": "${!Deals.Account_Name.Created_By}",
                            "id": "6660682000000002453"
                        },
                        "type": "merge_field"
                    },
                    {
                        "resource": {
                            "name": "Patricia Boyle",
                            "id": "6660682000000501001"
                        },
                        "type": "user"
                    },
                    {
                        "details": {
                            "api_name": "${!Deals.Contact_Name.Email}",
                            "id": "6660682000000002497"
                        },
                        "type": "merge_field"
                    },
                    {
                        "resource": {
                            "name": "UserGroup",
                            "id": "6660682000001441002"
                        },
                        "type": "group"
                    },
                    {
                        "resource": {
                            "name": "CEO",
                            "id": "6660682000000026005"
                        },
                        "type": "role_and_subordinate"
                    },
                    {
                        "resource": {
                            "name": "Territory_EU",
                            "id": "6660682000001453003"
                        },
                        "type": "territory"
                    }
                ]
            },
            "reply_to_address": {
                "resource": {
                    "id": "6660682000000501001"
                },
                "type": "user"
            },
            "template": {
                "name": "Big Deal Alert",
                "id": "6660682000000000079"
            }
        }
    ]
}
}

Possible Errors

  • INVALID_MODULEHTTP 400

    The module name given seems to be invalid.
    Resolution: Specify a valid module name.

  • AMBIGUITY_DURING_PROCESSING HTTP 400

    The given module api_name seems to be invalid.
    Resolution:  The module's unique ID and API name seem to be mismatched. Please specify the correct module ID along with its corresponding API name. Use the GET Module Metadata API  to retrieve the API names and IDs of your modules.

  • AMBIGUITY_DURING_PROCESSING HTTP 400

    Some selected recipients are not available.
    Resolution:This error occurs when a valid value is not provided for recipient detail.

  • EXPECTED_FIELD_MISSINGHTTP 400

    Specify at least one field.
    Resolution: Specify a either ID or api_name for the module.

  • EXPECTED_FIELD_MISSINGHTTP 400

    Specify at least one field.
    Resolution: Specify a either ID or api_name for the module.

  • MULTIPLE_OR_MULTI_ERRORSHTTP 400

    This error occurs when there is issue in multiple keys or when there are issues in the recipient lists.
    Resolution: Check individual errors and rectify them.

  • INVALID_REQUEST_METHODHTTP 400

    Invalid HTTP method to access the API URL.
    Resolution: Check the HTTP Method of the request.

  • NO_PERMISSIONHTTP 400

    Permission denied.
    Resolution: This error occurs when the user doesn't have permission. Contact administrator to obtain manage workflow permission.

  • INVALID_DATAHTTP 400
    • Selected recipient is unavailable.
      Resolution: Give correct value for the recipients.
    • Invalid associated_to passed
      Resolution: The only supported value of associated_to is team_module.
    • The id given seems to be invalid
      Resolution: Check the details.json_path to see which id is passed incorrectly and pass correct id.
    • Please specify a valid from/To address
      Resolution: Provide a valid email address
    • Special characters not allowed
      Resolution: The email notification name should not contain any special characters.
    • The length of name has exceeded the limit
      Resolution: Maximum accepted characters for email notification name is 250.
  • OAUTH_SCOPE_MISMATCHHTTP 401

    You do not have the scope required to use this API.
    Resolution: Use the correct scope and generate the grant and access tokens.

  • AUTHORIZATION_ERRORHTTP 401

    Alert is associated with command center
    Resolution: The email notification is associated with command centre or marketplace and cannot be updated.

  • NOT_ALLOWEDHTTP 401
    Resolution: Try from administrator account.
  • AUTHENTICATION_FAILUREHTTP 401

    Authentication failed
    Resolution: Pass the access token in the request header of the API call.

  • INVALID_URL_PATTERNHTTP 404

    Please check if the URL trying to access is a correct one
    Resolution: The request URL specified is incorrect. Specify a valid request URL. Refer to Request URL section for details.

  • INTERNAL_ERRORHTTP 500

    Internal Server Error.
    Resolution: Unexpected and unhandled exception in the server. Contact support team.

Sample Response

Copied{
    "email_notifications": [
        {
            "code": "SUCCESS",
            "details": {
                "id": "6660682000001456001"
            },
            "message": "alert updated successfully",
            "status": "success"
        }
    ]
}