ServiceNow Fluent API reference › Reference › ServiceNow SDK › Building applications in source code › Building pro-code applications › Developing your application › Building applications

Release: Australia · Updated: 2026-03-12 · Official documentation · View source

Email Notification API - ServiceNow Fluent

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.

Parent Topic:ServiceNow Fluent API reference

Related topics

ServiceNow Fluent

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.

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.

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.

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.

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: ` \n \n `
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.

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
}