ApexEmailNotifications Metadata Type for Error Alerts

Why the ApexEmailNotifications Metadata Type Is Essential for Production Observability#

By default, when an unhandled Apex governor limit (System.LimitException: Too many SOQL queries: 101) or NullPointerException occurs in Production, Salesforce emails the LastModifiedBy user of the failing class or trigger. If that consultant or developer left the project two years ago, critical production failures go unnoticed.

ApexEmailNotifications (apexEmailNotifications/apexEmailNotifications.notifications-meta.xml) centralizes unhandled Apex Exception and Flow Fault emails (when Process Automation Settings → Send Process or Flow Error Email to → Apex Exception Email Recipients is enabled) to your DevOps PagerDuty, Slack email webhook, or engineering distribution list.

Key Metadata Fields on ApexEmailNotifications#

In SFDX source format, there is only one file per org: force-app/main/default/apexEmailNotifications/apexEmailNotifications.notifications-meta.xml

Real-World XML Example (apexEmailNotifications/apexEmailNotifications.notifications-meta.xml)#

<?xml version="1.0" encoding="UTF-8"?>
<ApexEmailNotifications xmlns="http://soap.sforce.com/2006/04/metadata">
    <apexEmailNotification>
        <email>salesforce-prod-alerts@acme.example.com</email>
    </apexEmailNotification>
    <apexEmailNotification>
        <email>pagerduty-sfdc-sev2@acme.example.com</email>
    </apexEmailNotification>
</ApexEmailNotifications>

Querying ApexEmailNotification via SOQL#

You can query the configured exception recipients in standard SOQL or the Tooling API:

SELECT Id, Email, UserId, User.Name, User.Username, User.IsActive, CreatedDate
FROM ApexEmailNotification
ORDER BY CreatedDate DESC

Senior Architect Best Practices & Gotchas#

• Prefer <email> Distribution Lists Over <user> Usernames: Using <email>sfdc-devops@acme.example.com</email> instead of <user>admin@acme.com</user> avoids sandbox username mismatch errors during CI/CD deployments and lets you manage alert membership in Google Workspace, Microsoft 365, or PagerDuty without redeploying Salesforce metadata!

Frequently asked questions

Why should every production org configure ApexEmailNotifications?

Without ApexEmailNotifications configured, unhandled Apex exceptions and Flow fault emails (when Send error email to Apex Exception Email Recipients is enabled in Process Automation Settings) are sent only to the developer who last modified the class or flow—who may no longer work at the company.

Can a single apexEmailNotification block contain both user and email?

No. Each apexEmailNotification entry must specify either a user (Salesforce username) or an email (external email address or distribution list), never both in the same block.

What happens to existing recipients in the org when you deploy ApexEmailNotifications?

Deploying apexEmailNotifications.notifications-meta.xml performs a full replacement! Any existing recipient in the target org that is not listed in your deployed XML file is immediately deleted.

Can you query ApexEmailNotifications recipients using SOQL?

Yes. Both standard SOQL and the Tooling API allow querying the ApexEmailNotification object to inspect Email, UserId, and User.Username.