---
checkId: check.integration.smtp
plugin: stellaops.doctor.integration
severity: warn
tags: [connectivity, email, smtp]
---
# SMTP Email Connectivity

## What It Checks
Reads the SMTP host from `Smtp:Host`, `Email:Smtp:Host`, or `Notify:Email:Host` and the port from the corresponding `:Port` key (defaulting to 587). Opens a raw TCP connection to the SMTP server with a 5-second timeout. The check **passes** if the TCP connection succeeds, **fails** on timeout, socket error, DNS failure, or connection refusal.

## Why It Matters
Email notifications deliver approval requests, security alerts, deployment summaries, and audit reports to operators who may not be monitoring Slack or the web UI. If the SMTP server is unreachable, these notifications silently fail. For organizations with compliance requirements, email delivery may be the mandated audit notification channel.

## Common Causes
- SMTP server is not running or is being restarted
- Firewall blocking SMTP port (25, 465, or 587)
- DNS resolution failure for the SMTP hostname
- Network unreachable between Stella Ops and the mail server
- Incorrect host or port in configuration
- ISP/cloud provider blocking outbound SMTP

## How to Fix

### Docker Compose
```bash
# Check SMTP configuration
grep 'SMTP__\|EMAIL__SMTP\|NOTIFY__EMAIL' .env

# Test TCP connectivity
docker compose exec gateway bash -c \
  "echo > /dev/tcp/smtp.example.com/587 && echo OK || echo FAIL"

# Update SMTP settings
echo 'Smtp__Host=smtp.example.com' >> .env
echo 'Smtp__Port=587' >> .env
echo 'Smtp__UseSsl=true' >> .env
docker compose restart platform
```

### Bare Metal / systemd
```bash
# Verify configuration
cat /etc/stellaops/appsettings.Production.json | jq '.Smtp'

# Test connectivity
telnet smtp.example.com 587
# or
nslookup smtp.example.com

# Update configuration
sudo nano /etc/stellaops/appsettings.Production.json
sudo systemctl restart stellaops-platform
```

### Kubernetes / Helm
```yaml
# values.yaml
smtp:
  host: smtp.example.com
  port: 587
  useSsl: true
  existingSecret: stellaops-smtp-creds   # Secret with username/password
```
```bash
helm upgrade stellaops ./chart -f values.yaml
```

## Verification
```
stella doctor run --check check.integration.smtp
```

## Related Checks
- `check.integration.slack` -- Slack notifications (alternative channel)
- `check.integration.teams` -- Teams notifications (alternative channel)