> For the complete documentation index, see [llms.txt](https://docs.pharos.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.pharos.ai/configuration-guide/error-tracking/apex-exception-tracking.md).

# Apex Exception Tracking

How Pharos captures unhandled Apex exceptions via the error email service and Apex Exception Email settings.

Pharos captures unhandled Apex exceptions by intercepting the exception notification emails that Salesforce sends when errors occur. This requires two pieces: an **email service** that Pharos creates, and **Apex Exception Email** settings that route those emails to it.

***

## How Exception Emails Become Logs

When an unhandled Apex exception occurs, Salesforce generates an exception email and sends it to all recipients configured in **Apex Exception Email**. Pharos adds its email service address to this list and receives a copy. It does not remove or replace any existing recipients—you continue to receive exception emails as before.

Pharos creates an **Inbound Email** record for each incoming exception email. This record is an intermediate object that stores the raw email. Pharos then parses the Inbound Email, extracts error details, and creates an enriched log record. The flow is: exception email → Inbound Email record → log record. When log creation succeeds, the Inbound Email is linked to the corresponding log. If processing fails, the Inbound Email will contain an error status, and Pharos will also create an internal log with the Pharos category detailing the failure.

```mermaid
graph TD
    A[Unhandled Apex exception occurs] --> B[Salesforce generates exception email]
    B --> C[Email sent to Apex Exception Email recipients]
    C --> D[Pharos email service receives copy]
    C --> E[Existing recipients receive copy]
    D --> F[Inbound Email record created]
    F --> G[Parse error details]
    G --> H[Create enriched log record]
    style A fill:#bf360c,stroke:#5d4037,color:#fff
    style F fill:#e3f2fd,stroke:#1565c0,color:#333
    style H fill:#2e7d32,stroke:#1b5e20,color:#fff
```

***

## The Pharos Email Service

Pharos creates an email service that receives Salesforce exception emails and converts them into log records. In Salesforce Setup, the **Apex Exception Email** setting lets you add users or custom email addresses as recipients. Pharos adds its email service address to this list so that when Salesforce sends exception notifications, they are routed to Pharos.

The email service is typically set up by the [Quick Start](https://docs.pharos.ai/configuration-guide/quick-start.md) wizard. It operates with a **context user**—the identity under which it processes incoming emails and creates log records. This is the [Pharos Running User](https://docs.pharos.ai/configuration-guide/the-basics/pharos-running-user.md), whose permissions determine what Pharos can access when enriching logs and handling errors. In Salesforce Setup, the context user is configured per email address on the Email Service (see **Setup → Email Services → ErrorEmailHandler**).

### Email Service Configuration in Salesforce

The Pharos error email service appears in **Setup → Email Services** as **ErrorEmailHandler**. You can view or edit the service there to see the associated Apex class, whether it is active, and the email addresses with their context users. Use **Activate** or **Deactivate** to enable or disable the service.

![ErrorEmailHandler email service configuration in Salesforce Setup](https://4264222071-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fdl9tmJ56lvwg5XY63QYr%2Fuploads%2Fgit-blob-5e3a184cddb3e7adaa211da8d7bdb1b69e489e5c%2Ferror-email-service-setup.png?alt=media)

***

## Apex Exception Email Settings

For Pharos to receive exception emails, the Pharos email service address must be listed as a recipient in **Setup → Apex Exception Email**. When you enable automated Apex exception tracking in Error Tracking, Pharos updates this setting to add its email service address as a recipient. All unhandled Apex exceptions will then be sent to Pharos (along with any other recipients you have configured).

{% hint style="warning" %}
**Don't Remove the Email Address:** If the Pharos email service address is removed from Apex Exception Email settings, automated error tracking for Apex exceptions will stop. If you suspect this has happened, re-add the address from the Error Tracking screen.
{% endhint %}

***

## What Gets Captured

The email service captures unhandled exceptions from a variety of execution contexts. Each context contributes different details to the log record.

| Context              | Captured Details                                          |
| -------------------- | --------------------------------------------------------- |
| **Triggers**         | Stack trace, error message, user context, governor limits |
| **Classes/Methods**  | Any unhandled exception with full context                 |
| **Batch Jobs**\*     | Batch class, failed method, scope, timing                 |
| **Queueable Jobs**\* | Async processing failures                                 |
| **Scheduled Jobs**\* | Timeouts, governor limit violations                       |

\* *These async contexts often require a separate* [*Batch Error Tracking*](https://docs.pharos.ai/configuration-guide/error-tracking.md#5-batch-error-tracking) *setting—see below.*

### Async Jobs: Why a Separate Setting Exists

Batch jobs, queueable jobs, and scheduled jobs are all async—they run in the background. While some async failures may trigger exception emails, Salesforce often does **not** send an email for these failures. They run during off-hours, complete without a user in context, and may fail silently. That is why Pharos has a separate [Batch Error Tracking](https://docs.pharos.ai/configuration-guide/error-tracking.md#5-batch-error-tracking) setting.

When enabled, Pharos runs a scheduled job that periodically queries Salesforce for failed async jobs (such as `AsyncApexJob` records with a Failed status), extracts the error details and stack trace from those records, and creates log records. This mining approach does not rely on exception emails—it actively polls for failures that would otherwise go unnoticed.

{% hint style="info" %}
**Related:** For the full automated error tracking story, see [Automated Error Tracking — Apex Exceptions](https://docs.pharos.ai/platform-overview/pharos-platform-architecture/logs/log-ingestion-methods/automated-error-tracking.md). For batch and bulk API failure capture, see [Error Tracking](https://docs.pharos.ai/configuration-guide/error-tracking.md).
{% endhint %}
