Create Email Notification

Input JSON

• feature_typestring, optional

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

• templateJSON object, mandatory

  Represents the name and ID of the email template.

• moduleJSON object, mandatory

  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, mandatory

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

  • toJSON array, mandatory

    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

• Email recipients can be added by providing direct email address in the below format

  Intended Recipient	Type	details.emails
  Email	emails	Email 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 Recipient	Type	resource.name
  A specific user in the context of a team module	user	{user_ID}
  All users having a profile within a specific team module	profile	{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 Recipient	Allowed 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, mandatory

  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

• Possible values for from_address and reply_to_address

  Type	Value	Format	Example
  merge_field	Email address of the current user	api_name as ${!Current.User.Email}	"reply_to_address":{"details":{"api_name":"${!Current.User.Email}"},"type":"merge_field"}
  	Email address of the record owner	api_name as ${!Record.Owner.Email}	"from_address":{"details":{"api_name":"${!Record.Owner.Email}"},"type":"merge_field"}
  user	Own/Other user's email address	resource.id.  For example, {user.ID of the user}	"reply_to_address":{"resource":{"id":"6660682000000501001"},"type":"user"}
  organization_email	Organization email address	resource.id like {org_email_ID of the organization}	"from_address":{"resource":{"id":"6660682000001442351"},"type":"organization_email"}

Possible Errors

• MANDATORY_NOT_FOUNDHTTP 400

  Required fields seem to be missing 
  Resolution: Specify all mandatory fields required to add email notification. Refer to the Input JSON section.

• 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.

• AMBIGUITY_DURING_PROCESSING HTTP 400

  Set bulk_email as true to pass cc
  Set bulk_email as true to pass bcc
  Resolution:Recipients can be added as cc or bcc only when bulk_email is set as true. Set bulk_email as true and try again.

• 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.
• DEPENDENT_MISMATCHHTTP 400
  • Roles, groups, and territories type emails in 'to' cannot be associated when bulk_email is true.
    Resolution: When you choose to send notifications as a single mass email, you cannot choose roles, groups, and territories as recipients. You must either select the users as individual users from the available users or manually enter their email addresses as the additional recipient field and try again.
  • Associated_to not supported for the selected type.
    Resolution: The only supported value of type when associated is given as team_module is emails.
  • reply_to_adress can not be associated for this 'to' address type
    from_adress can not be associated for this 'to' address type
    Resolution: When record owner,owner's manager,created_by alone is passed in to field, the from_address or reply_to_address cannot be associated. Remove from_address/ reply_to_address from the request and try again.
• 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.

• 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.