Watermark

What It Is

Watermarks are unique tracking identifiers that ServiceNow embeds in the headers and body of outbound notification emails to maintain conversation threading when replies come back through inbound email actions. They solve the fundamental problem of matching an arbitrary inbound email reply to the specific ServiceNow record that originated the conversation, even when email subjects get mangled by external systems or users modify the content. Without watermarks, every email reply would either create a new record or fail to route properly, breaking the entire email-based workflow integration that most enterprises depend on for customer service, incident management, and request fulfillment.

Architecturally, watermarks live in the Email application within the Notification module, specifically managed through the sys_email_watermark table and controlled by inbound email actions in the sysevent_email_action table. The watermark generation happens during notification rendering through the EmailWatermark script include, which creates a unique identifier based on the source record's sys_id, table name, and instance-specific salt. This identifier gets inserted into both the email headers and the message body, typically in a format like ref:_00Dxx0000:_50068000000abcd:ref that external email systems preserve during reply threading.

The watermark system integrates directly with ServiceNow's email parsing pipeline through the inbound email processor, which examines every incoming email for watermark patterns before applying routing rules. When an inbound email contains a valid watermark, the system extracts the encoded record information and updates the corresponding record with the email content, bypassing the normal email action conditions and field mappings. This direct routing mechanism ensures that customer replies to incident notifications automatically update the correct incident record, even if the customer changes the subject line or sends from a different email address than originally registered in the system.

You cannot function without watermarks in any scenario involving bidirectional email communication with external parties, particularly customer service portals, incident management workflows, or request fulfillment processes where stakeholders reply to automated notifications. Without proper watermarking, a customer replying to an incident notification would trigger your inbound email actions to create a duplicate incident rather than updating the original, fragmenting the conversation history and creating data integrity nightmares. Multi-tenant environments or shared service organizations face even greater risks, as misrouted emails could expose sensitive information to wrong customers or create compliance violations when email content lands in incorrect records.

Platform administrators primarily manage watermark configuration through notification templates and inbound email action setup, while developers customize the watermark generation logic through script includes and email processing business rules. The division typically puts notification template management and basic email action configuration in admin hands, while complex watermark parsing, custom watermark formats, or integration with external email systems requires developer intervention through scripted solutions. Integration specialists often inherit watermark troubleshooting when email routing breaks, requiring deep understanding of both the ServiceNow email pipeline and external email system behavior to diagnose threading failures.

Recent ServiceNow releases have enhanced watermark reliability through improved parsing algorithms and better handling of email clients that modify message formatting. Vancouver introduced more robust watermark extraction that handles HTML email mangling better, while Washington added support for custom watermark patterns through the glide.email.watermark.custom_pattern system property. Xanadu has strengthened the watermark validation process to prevent email spoofing attempts and added audit logging for watermark extraction failures, making troubleshooting significantly easier when email routing breaks in production environments.

Where to Find and Configure It

The primary watermark configuration lives at System Notification > Email > Inbound Actions where you configure how inbound emails with watermarks get processed and routed to records. Navigate to System Notification > Notifications to modify notification templates that generate the watermarks in outbound emails. The watermark generation settings and system properties are located under System Properties > System where properties starting with glide.email.watermark control the watermark behavior and formatting.

View watermark generation in action through System Logs > Emails where the sys_email table shows the complete email content including embedded watermarks. Access the underlying watermark data directly through System Definition > Tables and navigate to the sys_email_watermark table to see all generated watermarks and their associated records. Monitor email processing failures through System Logs > System Log > Email where watermark parsing errors get logged with detailed failure reasons.

How It Works Step by Step

Watermark processing operates through a two-phase system: generation during outbound notifications and extraction during inbound email processing. The generation phase occurs when ServiceNow sends a notification email, creating a unique identifier that encodes the source record's table and sys_id using the EmailWatermark script include. This watermark gets embedded into both the email subject line and message body using patterns that external email systems typically preserve during reply threading, ensuring the identifier survives common email client modifications like adding 'RE:' prefixes or changing fonts.

The extraction phase activates when inbound emails arrive through POP3 or IMAP polling, with the email processor scanning the entire message content for watermark patterns before applying any inbound email action conditions. When a valid watermark is found, ServiceNow decodes the embedded information to identify the target record and updates it directly with the email content, bypassing the normal field mapping process that would apply to non-watermarked emails. This direct routing ensures that replies automatically land in the correct record's activity stream or work notes field, maintaining conversation threading even when multiple stakeholders reply to the same notification.

The Execution Order

1. Notification engine triggers when a record meets notification conditions, loading the relevant notification template and target record data
2. EmailWatermark script include generates unique identifier by hashing the record's table name, sys_id, and instance-specific salt
3. Watermark gets inserted into notification template content through mail script processing, embedding in both subject and body
4. sys_email_watermark table records the watermark-to-record mapping for future reference and audit purposes
5. Outbound email gets sent through SMTP with watermark embedded, creating the email trail in sys_email table
6. Inbound email processor retrieves reply emails during POP3/IMAP polling, scanning entire message content for watermark patterns
7. Watermark extraction decodes the identifier to determine target table and record, validating against sys_email_watermark table
8. Email content gets written directly to target record's work notes or comments field, bypassing normal inbound email action conditions

// Common watermark extraction pattern in inbound email processing
var EmailWatermark = Class.create();
EmailWatermark.prototype = {
    extractWatermark: function(emailBody, emailSubject) {
        var watermarkPattern = /ref:(_[\w\d]+:_[\w\d]+):ref/gi;
        var matches = watermarkPattern.exec(emailBody + ' ' + emailSubject);
        
        if (matches && matches.length > 1) {
            var watermarkData = matches[1];
            var parts = watermarkData.split(':');
            
            if (parts.length >= 2) {
                var tablePrefix = parts[0];
                var recordId = parts[1];
                
                // Validate watermark exists in sys_email_watermark table
                var watermarkGr = new GlideRecord('sys_email_watermark');
                watermarkGr.addQuery('watermark', watermarkData);
                if (watermarkGr.query() && watermarkGr.next()) {
                    return {
                        table: watermarkGr.getValue('table'),
                        recordId: watermarkGr.getValue('document_id'),
                        isValid: true
                    };
                }
            }
        }
        return { isValid: false };
    }
};

Real-World Scenarios

Customer Service Incident Threading

Your customer service team needs customers to reply to incident notifications and have those replies automatically update the correct incident record, even when customers change the subject line or reply from different email addresses. The business requirement is maintaining conversation history in a single incident rather than creating duplicate incidents for each customer reply.

• Navigate to System Notification > Notifications and open your incident notification template
• In the Subject field, ensure it contains ${mail_script:watermark} embedded in the subject text
• Add ${mail_script:watermark} to the message body, typically at the bottom in white text or hidden div
• Configure inbound email action at System Notification > Email > Inbound Actions with Target table set to Incident [incident]
• Set Field mapping to map email body to Work notes field for customer replies

Watch for email clients that strip or modify hidden content, which can break watermark extraction. Test with multiple email providers (Gmail, Outlook, mobile clients) to ensure watermark preservation. Monitor the sys_email table for failed watermark extractions and consider enabling the glide.email.watermark.debug property for detailed logging during troubleshooting.

Service Request Approval Email Threading

Approvers need to respond to service request approval notifications via email, with their responses automatically updating the approval record and triggering workflow progression. The business needs email-based approvals to work reliably without requiring approvers to log into ServiceNow for simple approve/reject decisions.

// Inbound email action script for approval processing
(function runAction(current, event, email, emailParts, logger) {
    
    // Extract watermark to get approval record
    var watermarkUtil = new EmailWatermark();
    var watermarkData = watermarkUtil.extractWatermark(email.body_text, email.subject);
    
    if (watermarkData.isValid && watermarkData.table === 'sysapproval_approver') {
        var approvalGr = new GlideRecord('sysapproval_approver');
        if (approvalGr.get(watermarkData.recordId)) {
            
            // Parse email content for approval decision
            var emailContent = email.body_text.toLowerCase();
            var approvalDecision = '';
            
            if (emailContent.indexOf('approved') >= 0 || emailContent.indexOf('approve') >= 0) {
                approvalDecision = 'approved';
            } else if (emailContent.indexOf('rejected') >= 0 || emailContent.indexOf('reject') >= 0) {
                approvalDecision = 'rejected';
            }
            
            if (approvalDecision) {
                approvalGr.setValue('state', approvalDecision);
                approvalGr.setValue('comments', email.body_text);
                approvalGr.update();
                
                logger.info('Approval ' + approvalGr.getDisplayValue() + ' updated via email: ' + approvalDecision);
            }
        }
    }
    
})(current, event, email, emailParts, logger);

Be careful with approval email parsing logic as natural language processing can misinterpret approver intent, potentially auto-approving requests inappropriately. Always include clear instructions in approval notification templates about exact keywords to use, and consider implementing confirmation emails when approvals are processed via email. The approval workflow timing matters because watermark-based approvals bypass normal approval conditions, so ensure your email polling frequency aligns with business SLA requirements.

Multi-Instance Email Routing Protection

Your organization runs multiple ServiceNow instances (prod, test, dev) that share similar email addresses, and you need to prevent watermarked emails from one instance accidentally updating records in another instance when users forward or reply incorrectly. The requirement is ensuring watermark validation prevents cross-instance data corruption while maintaining reliable email threading within each environment.

• Configure unique instance identifiers by setting glide.email.watermark.instance_id system property differently on each instance
• Modify the EmailWatermark script include to validate instance ID during watermark extraction
• Enable glide.email.watermark.strict_validation property to reject watermarks from other instances
• Create monitoring business rules on sys_email table to alert when foreign watermarks are detected

The Classic Mistake

Admins frequently customize the glide.email.watermark.format system property to make emails look cleaner or match corporate standards, not realizing this breaks the parsing mechanism. The most common bad customization involves removing the table name or record ID components to create "prettier" reference numbers. For example, changing the default format from ${table}:${sys_id}:${counter} to something like REF-${counter} or using only the incident number without the sys_id.

// BAD: Custom watermark format that breaks parsing
// System Properties > System
glide.email.watermark.format = "TICKET-${number}"
glide.email.watermark.format = "REF-${counter}-${short_description}"
glide.email.watermark.format = "${company}-${number}"

// This results in watermarks like:
// TICKET-INC0010001
// REF-12345-Login Issues
// ACME-INC0010001

// ServiceNow cannot parse these back to find:
// - Which table the record belongs to
// - The actual sys_id of the record
// - The thread relationship

// Reply emails create new incidents instead of updating existing ones

When this happens, users see their email replies creating brand new tickets instead of adding work notes to the existing incident. ServiceNow's inbound email processor cannot extract the table name and sys_id from the malformed watermark, so it treats every reply as a new inbound email. The parsing logic in the EmailWatermark script include expects specific delimiters and components, and fails silently when they're missing. This creates a nightmare scenario where every customer reply generates a duplicate ticket, destroying the conversation thread and confusing both agents and customers.

// GOOD: Maintain required components while customizing appearance
// System Properties > System
glide.email.watermark.format = "[${table}:${sys_id}:${counter}] - ${number}"
glide.email.watermark.format = "ACME-REF [${table}:${sys_id}:${counter}]"
glide.email.watermark.format = "${number} [${table}:${sys_id}:${counter}]"

// This results in watermarks like:
// [incident:9d385017c611228701d22104cc95c371:1] - INC0010001
// ACME-REF [incident:9d385017c611228701d22104cc95c371:1]
// INC0010001 [incident:9d385017c611228701d22104cc95c371:1]

// ServiceNow can parse the bracketed section to find:
// - Table: incident
// - Record: 9d385017c611228701d22104cc95c371  
// - Thread: 1

// Pretty formatting is preserved while maintaining functionality

When to Use This vs Alternatives

Watermarks are the correct choice when you need reliable email thread tracking for customer-facing notifications where replies must update the original record. This is the only ServiceNow mechanism that can definitively match an inbound email reply to a specific record and conversation thread, making it essential for incident management, case management, and any workflow involving email correspondence with external parties.

When Watermarks Are the Right Choice

Use watermarks when external users need to reply to notification emails and have those replies automatically processed back into ServiceNow. Subject line parsing and sender matching are unreliable because email subjects get modified ("RE:", "FWD:") and users forward emails from different addresses. Watermarks provide the only foolproof method to maintain conversation threading across email systems. Email signatures, custom headers, and body parsing all fail when users modify emails, change clients, or use mobile devices that strip formatting.

When to Use Alternatives Instead

Skip watermarks for internal-only notifications where replies aren't expected or when using integration patterns like REST APIs, MID Server communications, or webhook callbacks. For internal team notifications, use simple notification templates without watermarks to avoid cluttering emails with unnecessary tracking codes. When building integrations with external systems that use their own tracking mechanisms (like third-party ITSM tools), rely on their native correlation IDs rather than forcing watermark adoption.

When You Need Both Watermarks and Alternatives

Combine watermarks with custom inbound email parsing when you need to handle both structured replies (from watermarks) and unstructured emails (new requests). Set up watermark-enabled notifications for existing ticket updates while maintaining separate email routing rules for new ticket creation. Use watermarks alongside integration spokes when building hybrid communication flows where some updates come via email and others through API calls, ensuring both paths can correlate back to the same record.

Platform Interactions & Side Effects

• Inbound Email Actions trigger when watermarked replies arrive, executing Business Rules and potentially causing infinite email loops if notifications are misconfigured
• The sys_email table stores every inbound email with watermark parsing results in the watermark and target_table fields
• Domain separation applies to watermark generation, causing cross-domain email replies to fail when users exist in different domains than their tickets
• ACLs on target tables prevent watermarked email updates when the inbound email processor lacks proper read/write permissions to the destination record
• Update Sets capture watermark format changes but not the sys_watermark table records, causing thread mismatches during environment promotions
• Notification suppression (email_suppress) prevents watermark generation, breaking reply threading for records created during bulk operations
• The watermark counter increments in sys_watermark with each outbound email, creating audit trails but potentially causing performance issues on high-volume notification scenarios
• Clone and update operations don't transfer watermark relationships, causing email replies to original records to update cloned records unexpectedly
• Email client security settings that strip or modify email headers can corrupt watermarks, especially in Outlook security zones and mobile email apps
• Scheduled jobs processing inbound emails run as the admin user context, bypassing normal user permissions but potentially triggering unexpected business rule behaviors

Debugging and Troubleshooting

The most common failure symptoms include email replies creating duplicate tickets instead of updating existing ones, customers complaining that their responses aren't being acknowledged, and agents seeing conversation threads that suddenly stop mid-conversation. Users typically report that "email stopped working" without realizing the underlying thread tracking has broken. From the admin perspective, you'll see spikes in new ticket creation corresponding to what should have been reply updates, and the sys_email table will show inbound emails with empty target_table and instance values.

Start debugging in System Log > All looking for entries from the EmailWatermark script include and inbound email processing jobs. The sys_email table provides the most direct insight - examine the watermark field to see what ServiceNow extracted from the original email, and check if target_table and instance fields are populated. Check the sys_watermark table to verify watermark records exist for your notifications, and examine the system property glide.email.watermark.format for formatting issues. Enable debug logging for the com.glide.notification logger to trace watermark generation and parsing.

Look for specific error messages like "Could not parse watermark from email" or "No matching record found for watermark" in the application logs. The debug output typically shows parsing failures as "Watermark format mismatch" or "Invalid watermark components." When watermarks are completely missing from outbound emails, you'll see "Notification sent without watermark" warnings, indicating the notification template isn't configured properly or watermark generation is disabled.

Diagnostic Checklist:

• Verify the glide.email.watermark.format system property contains ${table}:${sys_id}:${counter} components
• Check if watermark records exist in sys_watermark table for the problematic record
• Examine recent sys_email records to see if watermark parsing populated target_table and instance
• Test notification template by sending a sample email and verifying watermark appears in message body or subject
• Confirm inbound email actions are active and have proper conditions for your target tables
• Check domain separation settings if emails cross domain boundaries between users and records
• Review ACL permissions on target tables for the email processing user account

Quick Reference

• Watermarks have a maximum length of 255 characters and will be truncated if your format string generates longer values
• The counter component increments per outbound notification, not per reply, so a single incident can have watermarks ending in :1, :2, :3 for different notification events
• Deleting records from sys_watermark breaks existing email threads permanently - there's no recovery mechanism
• Watermark parsing ignores case sensitivity, so "INCIDENT" and "incident" in the table component are treated identically
• Email clients that convert plain text to HTML can corrupt watermarks by adding line breaks, especially in mobile email apps
• The ${watermark} variable only works in notification templates, not in business rule email scripts or manual email sends
• Watermark generation respects notification suppression flags, so bulk operations with setWorkflow(false) won't create watermark records
• Clone operations don't transfer watermark relationships, so cloned incidents will generate new watermark sequences starting from :1
• Extended tables inherit watermark behavior from parent tables, so custom incident extensions use "incident" as the table component, not the extended table name
• Inbound email processing runs every 2 minutes by default, so reply processing isn't instantaneous and can be delayed during system maintenance windows