Email Notification API - ServiceNow Fluent

  • Release version: Australia
  • Updated March 12, 2026
  • 13 minutes to read

    • The Email Notification API defines notifications [sysevent_email_action] that send automated emails based on database operations, custom events, or manual triggers.

    Note:
    For the latest ServiceNow Fluent API documentation and examples, see the ServiceNow Fluent API reference and ServiceNow SDK examples repository on GitHub.

    For general information about email notifications, see Email and SMS notifications.

    EmailNotification object

    Create an email notification [sysevent_email_action] specifying when to send it, who receives it, what it contains, and if it can be delivered in an email digest.

    For general information about creating email notifications, see Create an email notification.

    Table 1. Properties
    Name Type Description
    table Reference or String Required. The variable identifier or name of a table to which the notification applies. To define a table, use the Table API - ServiceNow Fluent.
    Note:
    Don’t select the Task [task] table, which is for extending other tables. Notifications that run on the Task table directly aren’t supported.
    triggerConditions Object Required. The conditions that trigger the notification. For more information, see triggerConditions object.
    name String A unique name for the email notification.
    description String A description of the purpose of the email notification.
    category Reference or String The variable identifier or name of a notification category for grouping notifications. To define a notification category, use the Record API - ServiceNow Fluent.

    Default: The default email category (c97d83137f4432005f58108c3ffa917a)
    notificationType String The type of notification.
    Valid values:
    • email: A standard email.
    • vcalendar: A meeting invitation. Meeting invitations aren't supported with email digests.

    Default: email
    active Boolean Flag that indicates whether the notification is active.

    Default: true
    mandatory Boolean Flag that indicates whether the notification is required.

    Default: false
    enableDynamicTranslation Boolean Flag that indicates whether to enable dynamic translation for the notification.

    Default: false
    emailContent Object The email content and formatting. For more information, see emailContent object.
    recipientDetails Object The email recipients. For more information, see recipientDetails object.
    digest Object The email digest content and formatting. For more information, see digest object.
    $meta Object Metadata for the application metadata.
    With the installMethod property, you can map the application metadata to an output directory that loads only in specific circumstances.
    $meta: {
      installMethod: 'String'
}
    Valid values for installMethod:
    • demo: Outputs the application metadata to the metadata/unload.demo directory to be installed with the application when the Load demo data option is selected.
    • first install: Outputs the application metadata to the metadata/unload directory to be installed only the first time an application is installed on an instance.
    		 
    import { EmailNotification } from '@servicenow/sdk/core'

EmailNotification({
    table: 'incident',
    name: 'Custom Event Notification',
    description: 'Triggered by custom event',
    category: 'c97d83137f4432005f58108c3ffa917a',  // Default email category sys_id
    triggerConditions: {
        generationType: 'event',
        eventName: 'custom.incident.escalated',
        order: 100
    },
    recipientDetails: {
        recipientUsers: ['6816f79cc0a8016401c5a33be04be441'],  // Admin user sys_id
        eventParm1WithRecipient: true,  // Event param 1 contains recipient
        isSubscribableByAllUsers: true
    },
    emailContent: {
        contentType: 'text/html',
        subject: 'Incident Escalated',
        messageHtml: '<p>An incident has been escalated.</p>'
    }
})

    triggerConditions object

    Configure the conditions that must be met for the notification to be sent.

    Note:
    If the same trigger generates multiple notifications, the system sends only one notification. The system considers all other notifications, even if they have a different subject and body, as duplicates. The Ignore Duplicates business rule controls this functionality.
    Table 2. Properties
    Name Type Description
    generationType String Required. The method of triggering the email notification.
    Valid values:
    • engine: Sends the notification when a record is inserted or updated.
    • event: Sends the notification when custom events occur.
    • triggered: Manually triggered notifications. The following properties don't apply if this property is set to triggered.
    onRecordInsert Boolean Flag that indicates whether to send the notification when a record is inserted.
    Note:
    Either this property or the onRecordUpdate property must be true.

    Default: false
    onRecordUpdate Boolean Flag that indicates whether to send the notification when a record is updated.
    Note:
    Either this property or the onRecordInsert property must be true.

    Default: false
    eventName String The name of a custom event to trigger sending the notification.

    This property is required if the value of the generationType property is event.
    affectedFieldOnEvent String The event parameter that contains the affected field.

    This property applies only if the generationType property is set to event.

    Valid values:
    • parm1
    • parm2
    weight Number The notification priority relative to duplicate notifications.

    Notifications that have the same target table and recipients are considered duplicates if the weights are different. If weights are same, an additional evaluation is done to check if the subject and the body (excluding watermark) are the same to qualify as duplicate notification. When there are duplicate notifications, the system only sends the notification with the highest weight. All other notifications are moved from the Outbox to the Skipped mailbox. The default value of 0 causes the system to send the notification (assuming the conditions are met).

    Maximum value: 1000

    Default: 0
    condition String A filter query that specifies the fields and values that must be true for users to access the object. For more information, see Operators available for filters and queries.
    advancedCondition String A JavaScript conditional statement that must return true or set a global answer variable to true to send the notification. For more information, see Advanced conditions for email notifications.
    Note:
    This property is evaluated in addition to other conditions that you set on the notification. Both the condition and advanced condition must evaluate to true to send the notification.
    itemTable Reference or String The variable identifier or name of the table to which the notification item refers. To define a table, use the Table API - ServiceNow Fluent.
    item String The item to use for the notification context.
    order Number The execution order of the notification.

    Maximum value: 9999

    Default: 100

    		 
    triggerConditions: {
    generationType: "engine",
    onRecordInsert: false,
    onRecordUpdate: true,
    weight: 100,
    condition: "priority=1^ORpriority=2^state!=6^state!=7", // High/Critical priority, not resolved/closed
    order: 100
}

    emailContent object

    Configure the contents of an email notification.

    Table 3. Properties
    Name Type Description
    contentType String The type of email content.
    Valid values:
    • text/html
    • text/plain
    • multipart/mixed

    Default: text/html
    template Reference or String The variable identifier or sys_id of an email template [sysevent_email_template]. To define an email template, use the Record API - ServiceNow Fluent.
    You can only specify an email template that meets one of the following conditions:
    • The template has the same scope and table as the notification.
    • The template has the same scope but has no specified table.
    • The template has the same table and is in the global scope.
    style Reference or String The variable identifier or sys_id of an email style [sys_email_style]. To define an email style, use the Record API - ServiceNow Fluent.
    subject String A subject line for the email. If empty, the system uses the Subject value from the email template.

    You can use the \${variable} format for variable references. Variables map to column names available from the notification table, its parent tables, and reference tables. Use variables to include values from a record in the table, such as the short description or comments and work notes.
    smsAlternate String A notification message to send specifically to SMS devices. The SMS alternate message is limited to 140 characters. If empty, the system uses the SMS alternate value from the email template.

    You can use the \${variable} format for variable references. Variables map to column names available from the notification table, its parent tables, and reference tables. Use variables to include values from a record in the table, such as the short description or comments and work notes.
    importance String The level of importance of the message.
    Valid values:
    • low
    • high
    includeAttachments Boolean Flag that indicates whether to include attachments from the notification trigger record with the email.

    Default: false
    omitWatermark Boolean Flag that indicates whether to omit the watermark attached to each email. For more information, see Watermarks on notification emails.

    Default: false
    from String The email address from which to send the notification.
    replyTo String The email address to which recipients can reply.
    pushMessageOnly Boolean Flag that indicates whether to send the notification only as a push notification to a mobile device.

    Default: false
    pushMessageList Array A list of variable identifiers or sys_ids of push messages [sys_push_notif_msg] to associate with the notification. To define a push notification, use the Record API - ServiceNow Fluent.
    Note:
    The push message and notification must be for the same table.
    forceDelivery Boolean Flag that indicates whether to bypass user notification preferences that would prevent a notification and send the notification anyway.

    Default: false
    messageHtml String The HTML content of the notification message. If empty, the system uses the message HTML from the email template.

    You can use the \${variable} format for variable references. Variables map to column names available from the notification table, its parent tables, and reference tables. Use variables to include values from a record in the table, such as the short description or comments and work notes.

    This property is required if the value of the contentType property is text/html or multipart/mixed.
    messageText String The plain text content of the notification message. If empty, the system uses the message text from the email template.

    You can use the \${variable} format for variable references. Variables map to column names available from the notification table, its parent tables, and reference tables. Use variables to include values from a record in the table, such as the short description or comments and work notes.

    This property is required if the value of the contentType property is text/plain or multipart/mixed.
    message String Deprecated. Message contents. 
    emailContent: {
    contentType: "text/html",
    subject: "CRITICAL: Incident \${number} - \${short_description}",
    messageHtml: `
            <div style="background-color: #ff4444; color: white; padding: 10px; border-radius: 5px;">
                <h2>CRITICAL INCIDENT ALERT</h2>
                <p><strong>Incident:</strong> \${number}</p>
                <p><strong>Priority:</strong> \${priority}</p>
                <p><strong>Description:</strong> \${short_description}</p>
                <p><strong>Assigned To:</strong> \${assigned_to.name}</p>
                <p><strong>Created:</strong> \${sys_created_on}</p>
                <p><a href="\${instance_url}/incident.do?sys_id=\${sys_id}" style="color: #ffffff; text-decoration: underline;">View Incident</a></p>
            </div>
        `,
    smsAlternate:
      "CRITICAL: Incident \${number} - \${short_description}. Priority: \${priority}. Assigned: \${assigned_to.name}",
    pushMessageList: ["mobile_push_notification_sys_id"], 
    forceDelivery: true, 
    importance: "high"
}

    digest object

    Configure the contents of an email digest that summarizes the activity for a selected notification and its target records during a specified time interval.

    For general information about email digests, see Email digests.

    Table 4. Properties
    Name Type Description
    allow Boolean Flag that indicates whether users to receive this notification as a digest. If false, all other properties of the digest object are ignored.

    Default: false
    default Boolean Flag that indicates whether digest mode is enabled by default for this notification.

    Default: false
    type String The type of digest.
    Valid values:
    • single: Sends the notification in an email digest when it’s triggered multiple times during the selected interval for a single target record, for example INC001 only.
    • multiple: Sends the notification in an email digest when it’s triggered multiple times during the selected interval for a multiple target record, for example INC001, INC002, and more.
    defaultInterval Reference or String The variable identifier or sys_id of a digest interval [sys_email_digest_interval] to use as the default time interval for digest delivery. To define a digest interval, use the Record API - ServiceNow Fluent.
    subject String A subject line for the email digest. If empty, the system uses the Subject value from the email template.

    You can use the \${variable} format for variable references. Variables map to column names available from the notification table, its parent tables, and reference tables. Use variables to include values from a record in the table, such as the short description or comments and work notes.
    html String The HTML content of the email digest.

    You can use the \${variable} format for variable references. Variables map to column names available from the notification table, its parent tables, and reference tables. Use variables to include values from a record in the table, such as the short description or comments and work notes.
    text String The plain text content of the email digest.

    You can use the \${variable} format for variable references. Variables map to column names available from the notification table, its parent tables, and reference tables. Use variables to include values from a record in the table, such as the short description or comments and work notes.
    template String The variable identifier or sys_id of an email template [sysevent_email_template]. To define an email template, use the Record API - ServiceNow Fluent.
    separatorHtml String An HTML separator that appears between each item summarized in the digest.

    You can use the \${variable} format for variable references. Variables map to column names available from the notification table, its parent tables, and reference tables. Use variables to include values from a record in the table, such as the short description or comments and work notes.

    Default: <p>&nbsp;</p>\n<hr>\n<p>&nbsp;</p>
    separatorText String A plain text separator that appears between each item summarized in the digest.

    You can use the \${variable} format for variable references. Variables map to column names available from the notification table, its parent tables, and reference tables. Use variables to include values from a record in the table, such as the short description or comments and work notes.

    Default: --------------------------------------------------------------------------------\n
    from String The email address from which to send the notification.
    replyTo String The email address to which recipients can reply. 
    digest: {
    allow: true,
    defaultInterval: hourlyDigest,
    template: escalationTemplate,
    subject: "Incident Escalation Digest - \${digest_count} incidents require attention",
    html: `<div>
           <div>Incident Escalation Digest</div>
           </div>`,
    separatorHtml: '<hr style="margin: 15px 0;">',
    from: "noreply@company.com",
    replyTo: "itsupport@company.com"
}

    recipientDetails object

    Configure who receives an email notification.

    Notification recipients must be active users defined as active users in the User [sys_user] table. They must also have a valid email address defined for their primary channel (device) in the Notification Device [cmn_notif_device] table. Your notification recipients must also have the appropriate notification preferences enabled.

    Table 5. Properties
    Name Type Description
    recipientUsers Array A list of variable identifiers or sys_ids of users [sys_user] or a list of email addresses to receive the notification. To define a user, use the Record API - ServiceNow Fluent.
    recipientFields Array A list of fields that reference the users or user groups to receive the notification. The fields must be reference fields.

    For example, if a notification uses the Incident [incident] table, you can specify the opened_by field to send the notification to users or groups who opened the incident. This list of users or groups is variable and depends on the values of the associated task record. You can also select a field that includes an email address string to send a notification to that address.
    recipientGroups Array A list of variable identifiers or sys_ids of user groups [sys_user_group] to receive the notification. To define a user group, use the Record API - ServiceNow Fluent.
    Note:
    Group members receive individual notifications only if Include members is selected in the group record.
    excludeDelegates Boolean Flag that indicates whether to exclude delegated users. Set this property to true to help prevent the instance from sending email notifications to delegates of the users and members of the groups you selected.

    Default: false
    isSubscribableByAllUsers Boolean Flag that indicates whether to allow all users to subscribe to the notification. For more information, see Subscription-based notifications.
    Note:
    If the record contains sensitive or protected data, consider restricting the recipient list only to those users and groups who normally have access to it, leaving the value of this property as false. You can also configure your notification content so that private or sensitive data isn’t exposed. For example, you could insert a link back to the associated record, so that details aren’t revealed in the notification.

    Default: false
    sendToCreator Boolean Flag that indicates whether to send the notification to the person who performed the action that started the notification process, if the person is also a recipient. If the event creator isn’t specified in one of the recipient fields, the event creator doesn’t receive a notification regardless of the setting in this field.

    Default: false
    eventParm1WithRecipient Boolean Flag that indicates whether the event parameter 1 contains one or more notification recipients.

    This property only applies to event-based notifications.
    eventParm2WithRecipient Boolean Flag that indicates whether the event parameter 2 contains one or more notification recipients.

    This property only applies to event-based notifications.

    		 
    recipientDetails: {
    recipientGroups: ["d625dccec0a8016700a222a0f7900d06"], // IT Support group sys_id
    recipientFields: ["assigned_to", "caller_id"],
    sendToCreator: false,
    isSubscribableByAllUsers: false
}