Troubleshoot and Debug Message Processing on ESA

Introduction

This document describes how to use the Trace tool to debug how a message is processed through the Email Security Appliance (ESA).

Troubleshoot and Debug Message Processing on ESA

Administrators need to understand how a specific email message was processed by the Cisco Email Security Appliance (ESA). When a message is unexpectedly delivered, blocked, modified, quarantined, or rejected, it can be difficult to determine which ESA policy, rule, or mail flow decision affected it. This article explains how to debug message processing on the ESA so administrators can trace message handling and identify why the appliance took a specific action. Trace emulates a message as being accepted by a listener and prints a summary of features that would have been triggered or affected by the current configuration of the system (including uncommitted changes).

Note: The test message is not actually sent.

1. In the GUI, choose System Administration > Trace. Alternatively, in the CLI, run the trace command.

2. Enter the trace values required to emulate sending a test message through the system.

3. Click Start Trace.

4. Review the printed summary of all configured system features that affect the message.

5. To test with a message body from the local file system, click Upload Message Body.

6. In the CLI, test with message bodies uploaded to the /configuration directory.

An illustration of how to use Trace is shown in the video below:

Note: The sections of configuration tested by the trace command listed are performed in order. This can be extremely helpful to understand how the configuration of one feature affects another. For example, a recipient address transformed by the domain map feature affects the address as it is evaluated by the recipient access table (RAT). A recipient affected by the Recipient Access Table (RAT) continues to influence how the address is evaluated by the alias table and subsequent processing steps.

Tip: See the online help from your appliance GUI for full, detailed information.  First, click System Administration > Trace to visit the trace tool, and then select Help and Support > Online Help from the upper right-hand corner of the GUI.

Related Information

• Cisco Email Security Appliance - End-User Guides
• Technical Support & Documentation - Cisco Systems

Revision History

Revision	Publish Date	Comments
2.0	07-Jul-2026	Recertification
1.0	29-Jul-2014	Initial Release