> 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/platform-overview/pharos-platform-architecture/alerting/notification-channels/email.md).

# Email

Configure email notifications with caution about their limitations for observability.

Email notifications provide a simple, universally accessible channel for error awareness without requiring integration setup. However, email has significant limitations for real-time observability and should be used thoughtfully as part of a broader notification strategy.

## Why Email for Observability?

Email serves specific use cases where its characteristics are advantageous:

**No Integration Required:** Email works out-of-the-box using Salesforce's native email capabilities. No OAuth setup, no external service configuration—just specify recipient addresses.

**Universal Access:** Every stakeholder has email, even non-technical business users who don't use Slack or Teams.

**External Recipients:** Easily notify external vendors, contractors, or partners who don't have access to internal communication tools.

**Audit Trail:** Emails provide a built-in record of notifications sent, useful for compliance documentation.

**Digest Mode:** Email excels at scheduled summaries (daily/weekly digests) rather than real-time alerts.

However, these advantages come with significant trade-offs.

## Why Email Is NOT Ideal for Observability

The same traits that make email convenient also make it a poor fit for real-time monitoring. The problems below explain why.

{% hint style="warning" %}
**Email Limitations for Real-Time Monitoring**

While email works for specific use cases, it's **not recommended as the primary notification channel** for production error monitoring. Use Slack, Teams, or PagerDuty for real-time awareness.
{% endhint %}

**Problem 1: Low Visibility**

Emails compete with hundreds of other messages in inboxes:

* Easily missed or overlooked
* No dedicated space (unlike #prod-errors Slack channel)
* Mixed priority (critical errors next to meeting invites)
* Spam filters may block automated messages

**Problem 2: Poor Collaboration**

Email lacks features for team troubleshooting:

* No threaded discussions (replies create messy email chains)
* No real-time visibility (can't see who's investigating)
* Difficult to track resolution status
* Context gets lost across multiple reply chains

**Problem 3: Delayed Response**

Team members check email less frequently than chat:

* Chat: Checked constantly, real-time awareness
* Email: Checked periodically, delayed awareness
* Critical issues may sit in inbox for hours

**Problem 4: Notification Fatigue**

High-volume error notifications overwhelm inboxes:

* 50 errors per day = 50 emails
* Creates "delete without reading" habit
* Critical issues buried in noise

**Problem 5: No Interactive Features**

Unlike Slack/Teams, email doesn't support:

* Direct links that open in-app (often redirected)
* Real-time status updates
* Easy acknowledgment or assignment
* Rich formatting (often rendered as plain text)

## Valid Use Cases for Email

Despite limitations, email serves specific scenarios well.

### Use Case 1: Daily/Weekly Digests

**Scenario:** Non-urgent error summaries for review during business hours.

**Configuration:**

```
Rule Type: Digest (scheduled daily at 8 AM)
Filter: Category = "Apex" AND Created Date = Yesterday
Recipients: data-team@company.com, manager@company.com
Template: Daily summary with top 10 issues by occurrence count
```

**Why This Works:**

* Not time-sensitive (batch jobs can wait until morning)
* Summary format reduces email volume (1 per day instead of 50)
* Business stakeholders informed without noise

### Use Case 2: External Vendor Notifications

**Scenario:** Integration failure with external vendor requires escalation to their support team.

**Configuration:**

```
Rule Type: Notification (Is_Update__c = false)
Filter: Functional Area = "Integration" AND External System = "PaymentGateway"
Recipients: support@paymentgateway.com, internal-integration-team@company.com
Template: Integration failure details with logs and timestamps
```

**Why This Works:**

* External recipients can't access internal Slack/Teams
* Creates support ticket trail via email
* CC'd internal team stays informed

### Use Case 3: Executive/Stakeholder Updates

**Scenario:** Business leaders want visibility into production health without monitoring Slack.

**Configuration:**

```
Rule Type: Digest (scheduled weekly, Monday 9 AM)
Filter: Created Date = Last Week
Recipients: vp-engineering@company.com, director-it@company.com
Template: 
  - Total issues created last week
  - Top 3 issues by user impact
  - Resolution metrics
  - Trend comparison (vs. previous week)
```

**Why This Works:**

* Executive-appropriate summary format
* Asynchronous (doesn't require real-time monitoring)
* Provides visibility without overwhelming detail

### Use Case 4: Compliance/Audit Notifications

**Scenario:** Security or compliance team requires notification record for audit purposes.

**Configuration:**

```
Rule Type: Notification (Is_Update__c = false)
Filter: Log Level = "ERROR"
Recipients: security-team@company.com, compliance@company.com
Template: Detailed security incident report
```

**Why This Works:**

* Email provides audit trail (who was notified, when)
* Meets compliance documentation requirements
* Can be archived per retention policies

### Use Case 5: Fallback Notification

**Scenario:** Critical PagerDuty integration fails; need backup notification method.

**Configuration:**

```
Rule Type: Notification (Is_Update__c = false)
Filter: Priority = "Highest"
Recipients: on-call-team@company.com (distribution list)
Template: Critical issue alert with direct Pharos link
```

**Why This Works:**

* Redundancy ensures notification delivery
* Distribution list reaches entire on-call rotation
* Backup for primary notification channel

## When NOT to Use Email

Some configurations turn email's weaknesses into active liabilities. Avoid the following patterns.

### Anti-Pattern 1: High-Volume Real-Time Alerts

```
❌ Bad Configuration:
Rule Type: Notification (Is_Update__c = false)
Filter: (none - all issues)
Recipients: team@company.com

Result: 50 issues/day = 50 emails = inbox overwhelmed = emails ignored
```

**Solution:** Use Slack/Teams for real-time alerts, email for digests only.

### Anti-Pattern 2: Time-Sensitive Alerts

```
❌ Bad Configuration:
Rule Type: Notification (Is_Update__c = false)
Filter: Priority = "Highest" AND Functional Area = "Payment Processing"
Recipients: payments-team@company.com

Problem: Critical payment failure sits in inbox for 2 hours until someone checks email
```

**Solution:** Use PagerDuty or Slack with @channel mentions for time-sensitive alerts.

### Anti-Pattern 3: Individual Log Notifications

```
❌ Bad Configuration:
Rule Type: Notification (log-level, SobjectType__c = Log__c)
Recipients: dev-team@company.com

Result: Same error 100 times = 100 emails = unsubscribe requests
```

**Solution:** Use issue-level notifications (grouped errors) instead of log-level.

### Anti-Pattern 4: Collaborative Troubleshooting

```
❌ Bad Practice:
Team replies to error notification email to discuss troubleshooting

Problem: 
  - Reply chains become messy
  - Can't see who's investigating
  - Context lost across multiple threads
```

**Solution:** Use Slack/Teams for collaborative troubleshooting with threads.

## Email Notification Configuration

Email is the one channel that needs no integration at all — it uses Salesforce's own delivery, so it works the moment Pharos is installed. That makes it the natural fallback when a recipient has no access to Slack or Teams, or when an audit trail in a mailbox is itself the requirement.

An email action carries a subject and a message body, both supporting the same merge fields as any other channel, plus optional CC recipients and a Salesforce email template if you want branded formatting rather than plain output.

Links in emails open in the browser and may prompt for Salesforce login if the reader isn't already authenticated — a small friction that matters when the recipient is on a phone and the notification was meant to be urgent.

For the action's fields, see [Notification Actions](https://docs.pharos.ai/configuration-guide/notifications/notification-actions.md#email).

## Email Best Practices

When email fits a use case, a few practices keep it effective and manageable.

### Use Digest Mode Over Real-Time

**Poor Approach:**

```
Every issue → Immediate email
Result: 50 emails per day
```

**Better Approach:**

```
Scheduled daily summary → 1 email per day
Content: Top 10 issues, total counts, trends
Result: Manageable volume, still informed
```

### Clear Subject Lines

Make subject lines scannable and actionable:

**Good:**

```
Subject: [CRITICAL] Payment Processing Issue - 47 Users Impacted
Subject: Daily Digest: 12 New Issues in Production (Jan 29)
```

**Poor:**

```
Subject: Pharos Notification
Subject: New Issue Created
```

### Concise Message Bodies

Email readers skim quickly. Structure messages for scannability:

**Good Structure:**

```
[Critical Alert] Payment Integration Failure

Impact: 25 transactions failed in last 30 minutes
Functional Area: Payment Processing
Environment: Production

Next Steps:
1. Review issue in Pharos: [Link]
2. Check external payment gateway status
3. Escalate to vendor if external issue

Pharos Issue: https://...
```

**Poor Structure:**

```
A new issue was created. The category is Apex. The type is HTTP Timeout. 
The functional area is Payment. There have been 25 occurrences. The first 
occurrence was at 10:15 AM. [Full stack trace follows...]

[Wall of text continues for 5 paragraphs]
```

### Include Direct Links

Always include direct links to Pharos for full details:

```
View Issue: https://yourinstance.salesforce.com/apex/pharos__issueDetail?id=a1b2c3
View Logs: https://yourinstance.salesforce.com/apex/pharos__logs?issueId=a1b2c3
```

**Why:** Email should be entry point, not final destination. Recipients click through to Pharos for investigation.

### Distribution Lists Over Individual Emails

**Good:**

```
Recipients: production-errors@company.com (distribution list)
```

**Poor:**

```
Recipients: john@company.com, sarah@company.com, mike@company.com, jane@company.com
```

**Why:** Distribution lists are easier to maintain. When team members change, update the list, not every notification rule.

## Combining Email with Other Channels

Email works best as **part of a multi-channel strategy**, not as the sole notification method.

### Recommended Pattern: Real-Time + Digest

**For Development Teams:**

```
Real-Time: Slack #prod-errors (all issues)
Daily Digest: Email to team@company.com (summary of yesterday's issues)

Result: Team has real-time awareness (Slack) + daily recap (Email)
```

**For Business Stakeholders:**

```
Real-Time: Slack #prod-critical (critical only, with @channel)
Weekly Digest: Email to stakeholders@company.com (high-level summary)

Result: Stakeholders informed without real-time monitoring burden
```

### Recommended Pattern: Primary + Fallback

**For Critical Alerts:**

```
Primary: PagerDuty (on-call escalation)
Fallback: Email to on-call@company.com (backup notification)

Result: If PagerDuty fails, team still receives email alert
```

## Email Deliverability Considerations

Automated, high-volume notifications face delivery constraints that ordinary email doesn't—spam filters, org-wide send limits, and per-email recipient caps.

### Spam Filters

Automated error notifications may trigger spam filters:

**Risk Factors:**

* High volume (50+ emails per day to same recipient)
* Generic subject lines ("New Issue Created")
* Lack of unsubscribe link (required for some corporate filters)
* Sender reputation (Salesforce email server IPs)

**Mitigation:**

* Use digest mode (reduces volume)
* Descriptive subject lines with actionable info
* Whitelist Salesforce email IPs in corporate email system
* Test deliverability before rolling out

### Email Server Limits

Salesforce has email sending limits:

**Limits:**

* Standard: 5,000 emails per day per org (all sources combined)
* Unlimited: Higher limits available

**Implication:** High-volume log-level email notifications can exhaust daily limits. Use issue-level notifications and digest mode.

### Recipient Limits per Email

Salesforce limits recipients per email:

* \~100 recipients per notification (varies by configuration)

**Workaround:** Use distribution lists (counts as 1 recipient) rather than individual addresses.

## Real-World Example

**Organization:** 60-person engineering team with distributed stakeholders

**Initial Setup (Poor):**

```
Every issue → Email to all-engineers@company.com
Volume: 40-60 emails per day
Feedback: "Emails ignored, marks as read without reviewing"
```

**Revised Setup (Better):**

```
Real-Time:
  Slack #prod-errors → All issues (dev team monitors actively)
  PagerDuty → Critical only (on-call rotation)

Digest:
  Daily email at 8 AM → team-leads@company.com
    - Summary of yesterday's issues
    - Top 5 by user impact
    - Unresolved critical issues

  Weekly email Monday 9 AM → executives@company.com
    - Weekly summary
    - Trend analysis
    - Key resolved issues

Results:
  - Email volume reduced from 50/day to 1/day per recipient
  - Email open rate increased from 20% to 85%
  - Real-time issues handled via Slack (much faster)
  - Stakeholders informed without noise
```

## Summary

Email notifications have a place in your observability strategy, but should be used thoughtfully:

**Use Email For:**

* Daily/weekly digest summaries
* External vendor notifications
* Executive/stakeholder updates
* Compliance audit trails
* Fallback/redundancy

**Don't Use Email For:**

* Real-time production monitoring (use Slack/Teams)
* Time-sensitive critical alerts (use PagerDuty)
* High-volume notifications (causes fatigue)
* Collaborative troubleshooting (use chat threads)

**Best Practices:**

* Prefer digest mode over real-time
* Use distribution lists for maintainability
* Include direct Pharos links
* Clear, actionable subject lines
* Combine with Slack/Teams for real-time awareness

**Key Takeaway:** Email is a **supplementary** notification channel, not a primary one. Build your observability strategy around Slack/Teams/PagerDuty for real-time awareness, and use email for digests and stakeholder updates.

For real-time notification channels, see [Slack](https://docs.pharos.ai/platform-overview/pharos-platform-architecture/alerting/notification-channels/slack.md), [Microsoft Teams](https://docs.pharos.ai/platform-overview/pharos-platform-architecture/alerting/notification-channels/teams.md), and [PagerDuty](https://docs.pharos.ai/platform-overview/pharos-platform-architecture/alerting/notification-channels/pagerduty.md).
