checkId: check.notify.email.connectivity plugin: stellaops.doctor.notify severity: warn tags: [notify, email, smtp, connectivity, network, air-gap]

Email Connectivity

This Doctor check confirms that Stella Ops can actually reach the configured SMTP server over the network and that the server answers with a valid SMTP greeting. It is the transport companion to check.notify.email.configured(which only validates local settings) and is air-gap aware for sealed deployments.

What It Checks

Verifies that the configured SMTP server is reachable by opening a TCP connection to the SMTP host and port. The check:

• Opens a TCP socket to SmtpHost:SmtpPort with a 10-second timeout.
• Reads the SMTP banner and verifies it starts with 220 (standard SMTP greeting).
• Reports an info-level result if the connection succeeds but the banner is not a recognized SMTP response.
• Fails if the connection times out, is refused, or encounters a socket error.

The check only runs when both SmtpHost and SmtpPort are configured with valid values.

Air-Gap Behavior

When the deployment is sealed by AirGap policy, or STELLAOPS_DOCTOR_OFFLINE_PROFILE=true forces Doctor offline mode, external SMTP hosts return Skip with airGapSealed=true. Loopback, link-local, RFC1918, and unique-local IPv6 SMTP hosts are still probed so sealed deployments can validate internal mail relays. check.notify.email.configured still runs because it only validates local configuration.

For sealed deployments, route email through an internal relay or export notification queues for offline handling. Public SMTP services require egress and should remain disabled unless policy explicitly allows them.

Why It Matters

A configured but unreachable SMTP server means email notifications will silently fail. Release gate alerts, security finding notifications, and approval requests will never reach operators, potentially delaying incident response.

Common Causes

• SMTP server not running
• Wrong host or port in configuration
• Firewall blocking outbound SMTP connections
• DNS resolution failure for the SMTP hostname
• Network latency too high (exceeding 10-second timeout)

How to Fix

Docker Compose

Verify network connectivity from the container:

docker exec <notify-container> nc -zv smtp.example.com 587
docker exec <notify-container> nslookup smtp.example.com

Ensure the container network can reach the SMTP server. If behind a proxy, configure it:

environment:
  HTTP_PROXY: "http://proxy.example.com:8080"

Bare Metal / systemd

Test connectivity manually:

nc -zv smtp.example.com 587
telnet smtp.example.com 587
nslookup smtp.example.com

Check firewall rules:

sudo iptables -L -n | grep 587

Kubernetes / Helm

Verify connectivity from the pod:

kubectl exec -it <notify-pod> -- nc -zv smtp.example.com 587

Check NetworkPolicy resources that might block egress:

kubectl get networkpolicy -n stellaops

Verification

stella doctor run --check check.notify.email.connectivity

Related Checks

• check.notify.email.configured— verifies SMTP configuration is complete
• check.notify.queue.health— verifies the notification delivery queue is healthy