Email Notifications

Integrate Dokploy with email services to receive notifications about deployments, build failures, backups, and system events. Dokploy supports both custom SMTP servers and the Resend API.

Email Providers

Dokploy supports two methods for sending email notifications:

SMTP Email

Use any SMTP server (Gmail, Office 365, custom mail server, etc.)

Resend API

Use Resend’s modern email API for reliable delivery

SMTP Configuration

Prerequisites

Access to an SMTP server
SMTP credentials (username and password)
Admin access to your Dokploy organization

Common SMTP Settings

Gmail
Office 365
SendGrid
Mailgun

SMTP Server: smtp.gmail.com
Port: 587 (TLS) or 465 (SSL)
Username: your-email@gmail.com
Password: App-specific password (not your regular password)

Gmail requires App Passwords when 2FA is enabled. Generate one at myaccount.google.com/apppasswords

SMTP Server: smtp.office365.com
Port: 587
Username: your-email@company.com
Password: Your Office 365 password

SMTP Server: smtp.sendgrid.net
Port: 587
Username: apikey
Password: Your SendGrid API key

SMTP Server: smtp.mailgun.org
Port: 587
Username: postmaster@your-domain.mailgun.org
Password: Your Mailgun SMTP password

Configuring SMTP in Dokploy

Navigate to Notifications

In Dokploy, go to Settings > Notifications

Add Email Notification

Click Add Notification and select Email (SMTP)

Enter SMTP Configuration

Provide the following details:

Name: A descriptive name for this notification (e.g., “Production Email Alerts”)
SMTP Server: Your mail server hostname (e.g., smtp.gmail.com)
SMTP Port: Usually 587 (TLS) or 465 (SSL)
Username: SMTP authentication username
Password: SMTP authentication password
From Address: Email address that notifications will be sent from
To Addresses: Comma-separated list of recipient email addresses

Select Events

Choose which events should trigger email notifications:

Application Deploy
Application Build Error
Database Backup
Volume Backup
Dokploy Restart
Docker Cleanup
Server Threshold Exceeded

Test Connection

Click Test Connection to send a test email:Subject: Test Email
Body: Hi, From Dokploy 👋Check your inbox to verify the email arrives.

Save Configuration

Click Save to activate the notification channel

SMTP Configuration Schema

{
  name: string,                  // Display name for the notification
  smtpServer: string,            // SMTP server hostname (required)
  smtpPort: number,              // SMTP server port (required)
  username: string,              // SMTP authentication username (required)
  password: string,              // SMTP authentication password (required)
  fromAddress: string,           // Sender email address (required)
  toAddresses: string[],         // Array of recipient emails (required)
  appDeploy: boolean,            // Enable for deployment notifications
  appBuildError: boolean,        // Enable for build failure alerts
  databaseBackup: boolean,       // Enable for database backup notifications
  volumeBackup: boolean,         // Enable for volume backup notifications
  dokployRestart: boolean,       // Enable for Dokploy restart alerts
  dockerCleanup: boolean,        // Enable for cleanup notifications
  serverThreshold: boolean       // Enable for resource threshold warnings
}

Resend Configuration

Resend is a modern email API that offers reliable delivery, detailed analytics, and a developer-friendly experience.

Prerequisites

A Resend account (sign up at resend.com)
A verified domain in Resend
A Resend API key
Admin access to your Dokploy organization

Getting a Resend API Key

Create an account at resend.com

Verify Your Domain

Add and verify your domain in the Resend dashboard to send emails from your domain

Create API Key

Navigate to API Keys in the Resend dashboard
Click Create API Key
Give it a name (e.g., “Dokploy Notifications”)
Select permissions (send emails permission required)
Copy the API key (starts with re_)

Configuring Resend in Dokploy

Navigate to Notifications

In Dokploy, go to Settings > Notifications

Add Resend Notification

Click Add Notification and select Resend

Enter Resend Configuration

Provide the following details:

Name: A descriptive name for this notification (e.g., “Production Alerts”)
API Key: Your Resend API key (starts with re_)
From Address: Email address from your verified domain
To Addresses: Comma-separated list of recipient email addresses

Select Events

Choose which events should trigger email notifications

Test Connection

Click Test Connection to send a test email through Resend

Save Configuration

Click Save to activate the notification channel

Resend Configuration Schema

{
  name: string,                  // Display name for the notification
  apiKey: string,                // Resend API key (required)
  fromAddress: string,           // Sender email address (required, must be from verified domain)
  toAddresses: string[],         // Array of recipient emails (required)
  appDeploy: boolean,            // Enable for deployment notifications
  appBuildError: boolean,        // Enable for build failure alerts
  databaseBackup: boolean,       // Enable for database backup notifications
  volumeBackup: boolean,         // Enable for volume backup notifications
  dokployRestart: boolean,       // Enable for Dokploy restart alerts
  dockerCleanup: boolean,        // Enable for cleanup notifications
  serverThreshold: boolean       // Enable for resource threshold warnings
}

Email Format

Dokploy sends HTML-formatted emails with the following structure:

Subject Line: Concise event description
Body: HTML-formatted content with event details
Sender: Configured from address
Recipients: All addresses in the to addresses list

Example Notification Email

Subject: Build Error - my-app
Body:

<p><strong>Application Build Failed</strong></p>
<p>Application: my-app</p>
<p>Environment: production</p>
<p>Error: npm install failed</p>
<p>Timestamp: 2024-02-28T10:30:00Z</p>

Multiple Recipients

Both SMTP and Resend configurations support multiple recipients:

toAddresses: [
  "devops@company.com",
  "alerts@company.com",
  "admin@company.com"
]

All recipients receive the same notification. There is no differentiation between To, CC, or BCC fields.

Troubleshooting

SMTP Issues

Authentication failed

Verify username and password are correct
For Gmail, ensure you’re using an App Password, not your regular password
Check if your email provider requires special authentication

Connection timeout

Verify the SMTP server address is correct
Check that the port is correct (587 for TLS, 465 for SSL)
Ensure your server can reach the SMTP server (check firewall rules)

TLS/SSL errors

Try port 587 (STARTTLS) instead of 465 (SSL)
Some servers require explicit TLS configuration
Check if your SMTP provider has specific security requirements

Sender rejected

Verify the from address is allowed by your SMTP provider
Some providers only allow sending from verified addresses
Check if your domain has proper SPF/DKIM records

Resend Issues

Invalid API key

Verify you copied the complete API key from Resend
Check that the API key hasn’t been revoked
Ensure the API key has send permissions

Domain not verified

Verify your domain in the Resend dashboard
Add required DNS records (SPF, DKIM, DMARC)
Wait for DNS propagation (can take up to 48 hours)

From address domain mismatch

The from address must use a domain you’ve verified in Resend
You cannot send from arbitrary email addresses

General Issues

Emails going to spam

Configure SPF, DKIM, and DMARC records for your domain
Use a recognizable from address
Avoid spam trigger words in subject lines

Not receiving emails

Check spam/junk folders
Verify recipient addresses are correct
Test with a different recipient address
Check Dokploy logs for sending errors

Email passwords are stored encrypted in the database. If you update your email password with your provider, remember to update it in Dokploy as well.

Best Practices

Use Dedicated Email Addresses

Create dedicated email addresses or aliases for notifications:

✅ dokploy-alerts@company.com
✅ noreply@company.com
❌ Personal email addresses

Organize Recipients by Severity

Create multiple email notifications with different recipients:

// Critical alerts go to on-call team
{
  name: "Critical Alerts",
  toAddresses: ["oncall@company.com"],
  appBuildError: true,
  dokployRestart: true,
  serverThreshold: true
}

// Backups go to infrastructure team
{
  name: "Backup Notifications",
  toAddresses: ["infra@company.com"],
  databaseBackup: true,
  volumeBackup: true
}

Set Up Email Filtering

Use email filters to automatically:

Label Dokploy notifications
Route critical alerts to priority inbox
Archive routine backup notifications

SMTP vs Resend

Use SMTP when:

You already have an SMTP server
You need to use an existing corporate email infrastructure
You want complete control over email routing

Use Resend when:

You want modern, reliable API-based email
You need detailed delivery analytics
You want to avoid managing SMTP infrastructure

API Integration

Manage email notifications programmatically using the Dokploy API:

const notification = await api.notification.createEmail({
  name: "Production Alerts",
  smtpServer: "smtp.gmail.com",
  smtpPort: 587,
  username: "notifications@company.com",
  password: "app-password",
  fromAddress: "dokploy@company.com",
  toAddresses: ["team@company.com"],
  appDeploy: true,
  appBuildError: true,
  serverThreshold: true
});

Security Considerations

SMTP Password Security

Passwords are encrypted in the database
Use app-specific passwords when available
Rotate credentials periodically
Limit SMTP account permissions to send-only

API Key Security

Never commit API keys to version control
Use API keys with minimal required permissions
Rotate API keys regularly
Revoke unused keys immediately

Email Content

Email notifications may contain sensitive information
Consider what data is included in notifications
Use secure email recipients (internal addresses)
Avoid sending sensitive data via email when possible

Next Steps

Slack Notifications

Set up Slack webhook integration

Discord Notifications

Configure Discord webhooks

Telegram Notifications

Set up Telegram bot notifications

Notification Overview

Learn about all notification options

Git Providers

Notifications

Authentication

​Email Providers

SMTP Email

Resend API

​SMTP Configuration

​Prerequisites

​Common SMTP Settings

​Configuring SMTP in Dokploy

​SMTP Configuration Schema

​Resend Configuration

​Prerequisites

​Getting a Resend API Key

​Configuring Resend in Dokploy

​Resend Configuration Schema

​Email Format

​Example Notification Email

​Multiple Recipients

​Troubleshooting

​SMTP Issues

​Resend Issues

​General Issues

​Best Practices

​Use Dedicated Email Addresses

​Organize Recipients by Severity

​Set Up Email Filtering

​SMTP vs Resend

​API Integration

​Security Considerations

​SMTP Password Security

​API Key Security

​Email Content

​Next Steps

Slack Notifications

Discord Notifications

Telegram Notifications

Notification Overview

Email Providers

SMTP Configuration

Prerequisites

Common SMTP Settings

Configuring SMTP in Dokploy

SMTP Configuration Schema

Resend Configuration

Prerequisites

Getting a Resend API Key

Configuring Resend in Dokploy

Resend Configuration Schema

Email Format

Example Notification Email

Multiple Recipients

Troubleshooting

SMTP Issues

Resend Issues

General Issues

Best Practices

Use Dedicated Email Addresses

Organize Recipients by Severity

Set Up Email Filtering

SMTP vs Resend

API Integration

Security Considerations

SMTP Password Security

API Key Security

Email Content

Next Steps