Email configuration

Watchdog sends email notifications when monitored URLs experience status changes (healthy to unhealthy or vice versa). This guide covers SMTP configuration and email notification setup.

Overview

Email notifications are triggered by event listeners that respond to status change events published by the supervisor. When a monitored URL’s status changes, an email is sent to the configured contact address. Notification triggers:

URL goes from healthy to unhealthy (downtime alert)
URL recovers from unhealthy to healthy (recovery notification)
First check result for a new URL

SMTP configuration

Configure SMTP settings in your .env file:

.env

MAIL_FROM_ADDRESS="[email protected]"
MAIL_HOST=smtp.sendgrid.net
MAIL_PORT=587
MAIL_USERNAME=apikey
MAIL_PASSWORD=your_sendgrid_api_key

Environment variables

MAIL_FROM_ADDRESS

string

required

Sender email address that appears in the “From” field of notification emails.Examples:

[email protected] - Dedicated notifications address
[email protected] - Company alerts address
[email protected] - No-reply address

Ensure this address is authorized to send emails through your SMTP provider. Some providers require sender verification.

MAIL_HOST

string

required

SMTP server hostname.Common SMTP providers:

SendGrid: smtp.sendgrid.net
Mailgun: smtp.mailgun.org
Gmail: smtp.gmail.com
AWS SES: email-smtp.us-east-1.amazonaws.com
Mailtrap (dev/testing): sandbox.smtp.mailtrap.io

MAIL_PORT

integer

required

SMTP server port number.Common ports:

587 - SMTP with STARTTLS (recommended for production)
465 - SMTP over SSL/TLS
2525 - Alternative port (used by Mailtrap and some providers)
25 - Standard SMTP (often blocked by ISPs, not recommended)

Port 587 with STARTTLS is recommended for production deployments as it provides encryption and is widely supported.

MAIL_USERNAME

string

required

SMTP authentication username.Provider-specific notes:

SendGrid: Use apikey as the username
Mailgun: Use your Mailgun SMTP username
Gmail: Use your full Gmail address
AWS SES: Use your SMTP credentials username

MAIL_PASSWORD

string

required

SMTP authentication password or API key.Provider-specific notes:

SendGrid: Use your SendGrid API key
Mailgun: Use your Mailgun SMTP password
Gmail: Use an app-specific password (not your account password)
AWS SES: Use your SMTP credentials password

Never commit SMTP credentials to version control. Always use environment variables and keep your .env file gitignored.

Email implementation

Watchdog uses the gopkg.in/mail.v2 package for sending emails:

type SendEmailConfig struct {
	Recipients  []string
	Subject     string
	Content     string
	ContentType string
}

func SendEmail(emailConfig SendEmailConfig) error {
	message := gomail.NewMessage()

	emailTo := strings.Join(emailConfig.Recipients, ",")

	message.SetHeader("From", env.FetchString("MAIL_FROM_ADDRESS"))
	message.SetHeader("To", emailTo)
	message.SetHeader("Subject", emailConfig.Subject)

	message.SetBody(emailConfig.ContentType, emailConfig.Content)

	dialer := gomail.NewDialer(
		env.FetchString("MAIL_HOST"),
		env.FetchInt("MAIL_PORT"),
		env.FetchString("MAIL_USERNAME"),
		env.FetchString("MAIL_PASSWORD"),
	)

	if err := dialer.DialAndSend(message); err != nil {
		return err
	}

	log.Println("Email sent successfully to recipients:", emailConfig.Recipients)
	return nil
}

Features:

Multiple recipients support
Custom subject and content
Configurable content type (HTML or plain text)
Automatic SMTP connection management
Error handling and logging

Configuring recipient emails

When adding a URL to monitor, specify the contact email for notifications:

go run ./cmd/... add https://example.com get five_minutes [email protected]

Each monitored URL has its own contact email, allowing you to route notifications to different teams or individuals based on service ownership.

You can use the same contact email for multiple URLs, or set up distribution lists (e.g., [email protected]) to notify multiple people.

SMTP provider setup

SendGrid

Steps:

Create a SendGrid account at sendgrid.com
Generate an API key:
- Go to Settings → API Keys
- Click “Create API Key”
- Select “Restricted Access” and enable “Mail Send”
Verify your sender domain or single sender email
Configure your .env:

MAIL_FROM_ADDRESS="[email protected]"
MAIL_HOST=smtp.sendgrid.net
MAIL_PORT=587
MAIL_USERNAME=apikey
MAIL_PASSWORD=SG.your_api_key_here

Pricing: Free tier includes 100 emails/day

Mailgun

Steps:

Create a Mailgun account at mailgun.com
Add and verify your domain
Get your SMTP credentials from Settings → SMTP
Configure your .env:

MAIL_FROM_ADDRESS="[email protected]"
MAIL_HOST=smtp.mailgun.org
MAIL_PORT=587
MAIL_USERNAME=[email protected]
MAIL_PASSWORD=your_mailgun_smtp_password

Pricing: Free tier includes 5,000 emails/month for 3 months

Gmail

Steps:

Enable 2-factor authentication on your Google account
Generate an app-specific password:
- Go to myaccount.google.com
- Security → 2-Step Verification → App passwords
- Generate password for “Mail”
Configure your .env:

MAIL_FROM_ADDRESS="[email protected]"
MAIL_HOST=smtp.gmail.com
MAIL_PORT=587
MAIL_USERNAME=[email protected]
MAIL_PASSWORD=your_app_specific_password

Gmail limitations:

500 recipients per day for free accounts
2,000 recipients per day for Google Workspace
Not recommended for high-volume production use

AWS SES

Steps:

Create an AWS account and enable SES in your region
Verify your sender email or domain:
- Go to SES → Verified identities
- Add and verify your email/domain
Request production access (by default, SES starts in sandbox mode)
Create SMTP credentials:
- Go to SES → SMTP settings
- Click “Create SMTP Credentials”
Configure your .env:

MAIL_FROM_ADDRESS="[email protected]"
MAIL_HOST=email-smtp.us-east-1.amazonaws.com
MAIL_PORT=587
MAIL_USERNAME=your_smtp_username
MAIL_PASSWORD=your_smtp_password

Pricing: $0.10 per 1,000 emails, includes 62,000 free emails/month on AWS Free Tier

Mailtrap (Development/Testing)

Steps:

Create a Mailtrap account at mailtrap.io
Create an inbox (or use the default one)
Get SMTP credentials from inbox settings
Configure your .env:

MAIL_FROM_ADDRESS="[email protected]"
MAIL_HOST=sandbox.smtp.mailtrap.io
MAIL_PORT=2525
MAIL_USERNAME=your_mailtrap_username
MAIL_PASSWORD=your_mailtrap_password

Mailtrap captures emails instead of sending them to recipients. Perfect for development and testing without risking sending test emails to real users.

Testing email configuration

Verify your SMTP settings are working correctly:

Add a test URL

Add a URL to monitor with your email address:

go run ./cmd/... add https://httpstat.us/200 get one_minute [email protected]

Start the guard

Start the Watchdog monitoring service:

go run ./cmd/... guard

The first check will trigger a notification email.

Verify email delivery

Check your inbox (or Mailtrap inbox for testing) for the notification email.If using a dev SMTP provider like Mailtrap, verify the email appears in the inbox dashboard.

Test status change notifications

Trigger a status change by monitoring an unreliable endpoint:

# Add URL that randomly fails
go run ./cmd/... add https://httpstat.us/random/200,500 get thirty_seconds [email protected]

You should receive emails when the status changes between healthy and unhealthy.

Customizing email templates

The SendEmail function accepts a SendEmailConfig with customizable content:

core.SendEmail(core.SendEmailConfig{
	Recipients:  []string{"[email protected]"},
	Subject:     "Alert: example.com is down",
	Content:     "<h1>Status Change Detected</h1><p>Your site example.com is currently unreachable.</p>",
	ContentType: "text/html",
})

Content types:

text/plain - Plain text emails
text/html - HTML emails with formatting

To customize notification templates, modify the event listener code in events/listeners/ that calls SendEmail() in response to status change events.

Notification architecture

Email notifications are triggered by the event-driven architecture:

┌──────────────┐
│  Supervisor  │
└──────┬───────┘
       │ Publishes status change event
       ↓
┌──────────────┐
│  Event Bus   │
└──────┬───────┘
       │ Notifies listeners
       ↓
┌──────────────────┐
│ Email Listener   │ → Calls SendEmail()
└──────────────────┘

Event flow:

Child workers perform HTTP checks and send results to supervisor
Supervisor evaluates results and detects status changes
Supervisor publishes ping.successful or ping.unsuccessful events
Email listener subscribes to these events
On status change, listener calls SendEmail() with notification details
SMTP client sends email to configured recipient

Troubleshooting

SMTP authentication failed

Symptoms: SMTP AUTH failed or 535 Authentication failedSolutions:

Verify MAIL_USERNAME and MAIL_PASSWORD are correct
For Gmail, ensure you’re using an app-specific password, not your account password
Check if your SMTP provider requires sender verification
Verify your account is not suspended or has exceeded quotas

Connection timeout or refused

Symptoms: dial tcp: connect: connection refused or timeout errorsSolutions:

Verify MAIL_HOST and MAIL_PORT are correct
Check firewall rules allow outbound connections on the SMTP port
Try alternative ports (587, 465, 2525)
Verify your hosting provider doesn’t block SMTP connections

Emails not delivered (no errors)

Symptoms: SendEmail() succeeds but recipients don’t receive emailsSolutions:

Check recipient spam/junk folders
Verify sender domain has SPF and DKIM records configured
Check SMTP provider’s delivery logs for bounces
Verify MAIL_FROM_ADDRESS is authorized by your provider
Check if recipient email addresses are valid

SSL/TLS errors

Symptoms: x509: certificate signed by unknown authoritySolutions:

Ensure you’re using the correct port for your encryption method:
- Port 587 uses STARTTLS (encryption after connection)
- Port 465 uses implicit SSL/TLS (encrypted from start)
For self-signed certificates (development only), you may need to disable certificate verification
Update your system’s CA certificates: sudo update-ca-certificates

Rate limiting errors

Symptoms: 550 Rate limit exceeded or 429 Too Many RequestsSolutions:

Reduce monitoring frequency for URLs
Implement email throttling or batching
Upgrade your SMTP provider plan
Use separate SMTP accounts for different environments (dev/staging/prod)

Best practices

Use transactional email providers

Use dedicated transactional email services (SendGrid, Mailgun, AWS SES) instead of personal email accounts for better deliverability and reliability.

Configure sender authentication

Set up SPF, DKIM, and DMARC records for your sending domain to improve email deliverability and prevent spoofing:

; SPF record
@ IN TXT "v=spf1 include:_spf.google.com ~all"

; DMARC record
_dmarc IN TXT "v=DMARC1; p=quarantine; rua=mailto:[email protected]"

Monitor email delivery

Track email delivery success rates and bounce rates using your SMTP provider’s dashboard.Consider implementing retry logic for failed email sends.

Separate environments

Use different SMTP configurations for development, staging, and production:

Development: Mailtrap or similar email capture service
Staging: Separate SMTP account with test recipient lists
Production: Production SMTP account with real recipients

Implement email batching

For high-frequency monitoring, consider batching multiple status changes into digest emails to avoid overwhelming recipients and hitting rate limits.

Advanced configuration

Custom email content

To customize notification email content, modify the event listener that calls SendEmail():

subject := fmt.Sprintf("Alert: %s status changed to %s", url, status)
content := fmt.Sprintf(`
<html>
<body>
  <h2>Watchdog Status Alert</h2>
  <p><strong>URL:</strong> %s</p>
  <p><strong>Status:</strong> %s</p>
  <p><strong>Timestamp:</strong> %s</p>
  <p>Check the dashboard for more details.</p>
</body>
</html>
`, url, status, time.Now().Format(time.RFC1123))

core.SendEmail(core.SendEmailConfig{
	Recipients:  []string{contactEmail},
	Subject:     subject,
	Content:     content,
	ContentType: "text/html",
})

Multiple SMTP providers

For redundancy, implement fallback SMTP providers:

func SendEmailWithFallback(config SendEmailConfig) error {
	err := SendEmailViaPrimary(config)
	if err != nil {
		log.Printf("Primary SMTP failed: %v, trying fallback", err)
		return SendEmailViaFallback(config)
	}
	return nil
}

Email queueing

For high-volume deployments, consider implementing an email queue using Redis or a message broker to decouple email sending from event processing.

Get Started

Core Concepts

Configuration

Guides

Email configuration

Overview

SMTP configuration

Environment variables

Email implementation

Configuring recipient emails

SMTP provider setup

Testing email configuration

Customizing email templates

Notification architecture

Troubleshooting

Best practices

Advanced configuration

Custom email content

Multiple SMTP providers

Email queueing

Build docs developers (and LLMs) love

Get Started

Core Concepts

Configuration

Guides

​Overview

​SMTP configuration

​Environment variables

​Email implementation

​Configuring recipient emails

​SMTP provider setup

​Testing email configuration

​Customizing email templates

​Notification architecture

​Troubleshooting

​Best practices

​Advanced configuration

​Custom email content

​Multiple SMTP providers

​Email queueing

Build docs developers (and LLMs) love

Overview

SMTP configuration

Environment variables

Email implementation

Configuring recipient emails

SMTP provider setup

Testing email configuration

Customizing email templates

Notification architecture

Troubleshooting

Best practices

Advanced configuration

Custom email content

Multiple SMTP providers

Email queueing