Email Configuration

Configure email delivery using SMTP, Resend, MailChannels, or other providers

Documenso sends emails for signing invitations, notifications, and account management. You can configure email delivery using various providers.

Email Transports

Documenso supports four email transport methods:

• smtp-auth - Standard SMTP with username/password (default)
• smtp-api - SMTP with API key (e.g., SendGrid, Postmark)
• resend - Resend.com API
• mailchannels - MailChannels API (Cloudflare Workers)

Required Configuration

Regardless of the transport, you must configure the sender information:

NEXT_PRIVATE_SMTP_FROM_NAME · string · required

Sender name displayed in emails.

NEXT_PRIVATE_SMTP_FROM_NAME="Documenso"

NEXT_PRIVATE_SMTP_FROM_ADDRESS · string · required

Email address used as the sender.

NEXT_PRIVATE_SMTP_FROM_ADDRESS="[e-mail]"

SMTP with Authentication (Default)

Use standard SMTP with username and password. Works with most email providers.

Configuration

NEXT_PRIVATE_SMTP_TRANSPORT · string · default: "smtp-auth"

Set to "smtp-auth" for standard SMTP.

NEXT_PRIVATE_SMTP_TRANSPORT="smtp-auth"

NEXT_PRIVATE_SMTP_HOST · string · default: "127.0.0.1"

SMTP server hostname.

NEXT_PRIVATE_SMTP_HOST="smtp.gmail.com"

NEXT_PRIVATE_SMTP_PORT · number · default: "587"

SMTP server port.

• 587 - STARTTLS (recommended)
• 465 - SSL/TLS
• 25 - Unencrypted (not recommended)

NEXT_PRIVATE_SMTP_PORT=587

NEXT_PRIVATE_SMTP_USERNAME · string

SMTP username for authentication.

NEXT_PRIVATE_SMTP_USERNAME="[e-mail]"

NEXT_PRIVATE_SMTP_PASSWORD · string

SMTP password for authentication.

NEXT_PRIVATE_SMTP_PASSWORD="your-app-password"

NEXT_PRIVATE_SMTP_SECURE · string · default: "false"

Set to "true" to use SSL/TLS (port 465).

NEXT_PRIVATE_SMTP_SECURE="true"

NEXT_PRIVATE_SMTP_UNSAFE_IGNORE_TLS · string · default: "false"

Set to "true" to disable TLS even if the server supports STARTTLS.

Only use this for testing. Never disable TLS in production.

NEXT_PRIVATE_SMTP_UNSAFE_IGNORE_TLS="false"

NEXT_PRIVATE_SMTP_SERVICE · string

Predefined service configuration (e.g., “gmail”, “outlook”). Automatically configures host and port.

NEXT_PRIVATE_SMTP_SERVICE="gmail"

Provider Examples

Gmail

.env

NEXT_PRIVATE_SMTP_TRANSPORT="smtp-auth"
NEXT_PRIVATE_SMTP_SERVICE="gmail"
NEXT_PRIVATE_SMTP_USERNAME="[e-mail]"
NEXT_PRIVATE_SMTP_PASSWORD="your-app-password"
NEXT_PRIVATE_SMTP_FROM_NAME="Documenso"
NEXT_PRIVATE_SMTP_FROM_ADDRESS="[e-mail]"

Use an App Password, not your regular Gmail password.

Outlook/Office 365

.env

NEXT_PRIVATE_SMTP_TRANSPORT="smtp-auth"
NEXT_PRIVATE_SMTP_HOST="smtp.office365.com"
NEXT_PRIVATE_SMTP_PORT=587
NEXT_PRIVATE_SMTP_SECURE="false"
NEXT_PRIVATE_SMTP_USERNAME="[e-mail]"
NEXT_PRIVATE_SMTP_PASSWORD="your-password"
NEXT_PRIVATE_SMTP_FROM_NAME="Documenso"
NEXT_PRIVATE_SMTP_FROM_ADDRESS="[e-mail]"

Amazon SES

.env

NEXT_PRIVATE_SMTP_TRANSPORT="smtp-auth"
NEXT_PRIVATE_SMTP_HOST="email-smtp.us-east-1.amazonaws.com"
NEXT_PRIVATE_SMTP_PORT=587
NEXT_PRIVATE_SMTP_USERNAME="your-smtp-username"
NEXT_PRIVATE_SMTP_PASSWORD="your-smtp-password"
NEXT_PRIVATE_SMTP_FROM_NAME="Documenso"
NEXT_PRIVATE_SMTP_FROM_ADDRESS="[e-mail]"

Create SMTP credentials in AWS Console > SES > SMTP Settings.

Mailgun

.env

NEXT_PRIVATE_SMTP_TRANSPORT="smtp-auth"
NEXT_PRIVATE_SMTP_HOST="smtp.mailgun.org"
NEXT_PRIVATE_SMTP_PORT=587
NEXT_PRIVATE_SMTP_USERNAME="[e-mail]"
NEXT_PRIVATE_SMTP_PASSWORD="your-smtp-password"
NEXT_PRIVATE_SMTP_FROM_NAME="Documenso"
NEXT_PRIVATE_SMTP_FROM_ADDRESS="[e-mail]"

SMTP with API Key

Some providers (SendGrid, Postmark) use API keys for SMTP authentication.

Configuration

NEXT_PRIVATE_SMTP_TRANSPORT · string

Set to "smtp-api" for API key authentication.

NEXT_PRIVATE_SMTP_TRANSPORT="smtp-api"

NEXT_PRIVATE_SMTP_HOST · string · required

SMTP server hostname.

NEXT_PRIVATE_SMTP_HOST="smtp.sendgrid.net"

NEXT_PRIVATE_SMTP_APIKEY · string · required

API key for authentication.

NEXT_PRIVATE_SMTP_APIKEY="SG.xxxxxxxxxxxxxxxxxxxx"

NEXT_PRIVATE_SMTP_APIKEY_USER · string · default: "apikey"

Username for SMTP authentication (usually “apikey”).

NEXT_PRIVATE_SMTP_APIKEY_USER="apikey"

Provider Examples

SendGrid

.env

NEXT_PRIVATE_SMTP_TRANSPORT="smtp-api"
NEXT_PRIVATE_SMTP_HOST="smtp.sendgrid.net"
NEXT_PRIVATE_SMTP_PORT=587
NEXT_PRIVATE_SMTP_APIKEY_USER="apikey"
NEXT_PRIVATE_SMTP_APIKEY="SG.xxxxxxxxxxxxxxxxxxxx"
NEXT_PRIVATE_SMTP_FROM_NAME="Documenso"
NEXT_PRIVATE_SMTP_FROM_ADDRESS="[e-mail]"

Postmark

.env

NEXT_PRIVATE_SMTP_TRANSPORT="smtp-api"
NEXT_PRIVATE_SMTP_HOST="smtp.postmarkapp.com"
NEXT_PRIVATE_SMTP_PORT=587
NEXT_PRIVATE_SMTP_APIKEY_USER="your-server-token"
NEXT_PRIVATE_SMTP_APIKEY="your-server-token"
NEXT_PRIVATE_SMTP_FROM_NAME="Documenso"
NEXT_PRIVATE_SMTP_FROM_ADDRESS="[e-mail]"

Resend

Resend provides a modern email API with excellent developer experience.

Configuration

NEXT_PRIVATE_SMTP_TRANSPORT · string

Set to "resend" to use Resend.

NEXT_PRIVATE_SMTP_TRANSPORT="resend"

NEXT_PRIVATE_RESEND_API_KEY · string · required

Resend API key.

NEXT_PRIVATE_RESEND_API_KEY="re_xxxxxxxxxxxxxxxxxxxx"

Complete Example

.env

NEXT_PRIVATE_SMTP_TRANSPORT="resend"
NEXT_PRIVATE_RESEND_API_KEY="re_xxxxxxxxxxxxxxxxxxxx"
NEXT_PRIVATE_SMTP_FROM_NAME="Documenso"
NEXT_PRIVATE_SMTP_FROM_ADDRESS="[e-mail]"

Resend offers a generous free tier (100 emails/day) and is easy to set up. Recommended for getting started.

MailChannels

MailChannels is designed for Cloudflare Workers and serverless environments.

Configuration

NEXT_PRIVATE_SMTP_TRANSPORT · string

Set to "mailchannels" to use MailChannels.

NEXT_PRIVATE_SMTP_TRANSPORT="mailchannels"

NEXT_PRIVATE_MAILCHANNELS_API_KEY · string

Optional API key for authentication.

NEXT_PRIVATE_MAILCHANNELS_API_KEY="your-api-key"

NEXT_PRIVATE_MAILCHANNELS_ENDPOINT · string · default: "https://api.mailchannels.net/tx/v1/send"

Custom endpoint if using a proxy worker.

NEXT_PRIVATE_MAILCHANNELS_ENDPOINT="https://your-worker.workers.dev/send"

DKIM Signing (Optional)

NEXT_PRIVATE_MAILCHANNELS_DKIM_DOMAIN · string

Domain for DKIM signing.

NEXT_PRIVATE_MAILCHANNELS_DKIM_DOMAIN="example.com"

NEXT_PRIVATE_MAILCHANNELS_DKIM_SELECTOR · string

DKIM selector.

NEXT_PRIVATE_MAILCHANNELS_DKIM_SELECTOR="mailchannels"

NEXT_PRIVATE_MAILCHANNELS_DKIM_PRIVATE_KEY · string

DKIM private key.

NEXT_PRIVATE_MAILCHANNELS_DKIM_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\n..."

Complete Example

.env

NEXT_PRIVATE_SMTP_TRANSPORT="mailchannels"
NEXT_PRIVATE_MAILCHANNELS_API_KEY="your-api-key"
NEXT_PRIVATE_MAILCHANNELS_DKIM_DOMAIN="example.com"
NEXT_PRIVATE_MAILCHANNELS_DKIM_SELECTOR="mailchannels"
NEXT_PRIVATE_MAILCHANNELS_DKIM_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\nMIIEvQIB..."
NEXT_PRIVATE_SMTP_FROM_NAME="Documenso"
NEXT_PRIVATE_SMTP_FROM_ADDRESS="[e-mail]"

MailChannels is free for Cloudflare Workers. Set up a worker to proxy requests with authentication.

Testing Email Configuration

After configuration, test email delivery:

1. Start Documenso
2. Create a test account or reset password
3. Check that you receive the email
4. Verify the sender name and address

Testing with Mailpit (Development)

For local development, use Mailpit to catch all outgoing emails:

docker-compose.yml

services:
  mailpit:
    image: axllent/mailpit:latest
    ports:
      - "1025:1025"  # SMTP
      - "8025:8025"  # Web UI

.env

NEXT_PRIVATE_SMTP_TRANSPORT="smtp-auth"
NEXT_PRIVATE_SMTP_HOST="localhost"
NEXT_PRIVATE_SMTP_PORT=1025
NEXT_PRIVATE_SMTP_UNSAFE_IGNORE_TLS="true"
NEXT_PRIVATE_SMTP_FROM_NAME="Documenso"
NEXT_PRIVATE_SMTP_FROM_ADDRESS="[e-mail]"

Access the web UI at http://localhost:8025 to view sent emails.

Email Deliverability Best Practices

1. Configure SPF Records

   Add an SPF record to your domain’s DNS:

   example.com. IN TXT "v=spf1 include:_spf.google.com ~all"
   

   Replace with your provider’s SPF record.

2. Configure DKIM

   Enable DKIM signing in your email provider. Add the DKIM DNS records provided by your provider.

3. Configure DMARC

   Add a DMARC policy to your domain:

   _dmarc.example.com. IN TXT "v=DMARC1; p=quarantine; rua=mailto:[e-mail]"
   
4. Use a Dedicated Domain

   Send emails from a dedicated subdomain (e.g., mail.example.com) to protect your main domain’s reputation.

5. Verify Domain Ownership

   Complete domain verification with your email provider to improve deliverability.

6. Monitor Deliverability

   Use tools like:

   • Mail Tester
   • MXToolbox
   • Your email provider’s analytics

Troubleshooting

Emails not being sent

Possible causes:

• Incorrect SMTP credentials
• Firewall blocking outbound connections
• Wrong port configuration

Solution: Check logs for error messages and verify configuration.

”SMTP error: 535 Authentication failed”

Cause: Invalid username or password.

Solution:

• Verify credentials are correct
• For Gmail, use an App Password
• Check that 2FA is configured properly

”Connection timeout”

Cause: Firewall or network issue.

Solution:

• Verify the SMTP host is reachable: telnet smtp.example.com 587
• Check firewall rules
• Try a different port (587, 465, 25)

Emails going to spam

Cause: Poor domain reputation or missing authentication records.

Solution:

• Configure SPF, DKIM, and DMARC
• Use a dedicated IP (for high-volume senders)
• Avoid spam trigger words in email content
• Warm up your domain gradually

”550 Sender verify failed”

Cause: Sender address doesn’t match authenticated domain.

Solution: Ensure NEXT_PRIVATE_SMTP_FROM_ADDRESS matches your authenticated domain.

Provider Comparison

Provider	Setup	Cost	Deliverability	Best For
Resend	Easy	Free tier, then paid	Excellent	Getting started, modern API
SendGrid	Moderate	Free tier, then paid	Excellent	High volume
Amazon SES	Moderate	Pay per email	Excellent	AWS users, high volume
Postmark	Easy	Paid only	Excellent	Transactional emails
Gmail	Easy	Free (limited)	Good	Testing, very low volume
Mailgun	Moderate	Free tier, then paid	Excellent	Developers
MailChannels	Easy	Free (Cloudflare)	Good	Cloudflare Workers

Next Steps

Database Configuration

Optimize database settings

Background Jobs

Configure job processing