Documenso
Configuration

Email Configuration

Configure email delivery for notifications and document signing invitations.

Supported Email Transports

Documenso supports four email transport methods:

TransportUse CaseConfiguration Complexity
smtp-authStandard SMTP with username/passwordLow
smtp-apiSMTP with API key authenticationLow
resendResend.com email APILow
mailchannelsMailChannels API (Cloudflare Workers)Medium

Select a transport by setting the NEXT_PRIVATE_SMTP_TRANSPORT environment variable. The default is smtp-auth.

Sender Configuration

All transports require sender configuration:

VariableDescriptionRequired
NEXT_PRIVATE_SMTP_FROM_ADDRESSEmail address shown as the senderYes
NEXT_PRIVATE_SMTP_FROM_NAMEDisplay name shown as the senderYes
NEXT_PRIVATE_SMTP_FROM_ADDRESS="noreply@example.com"
NEXT_PRIVATE_SMTP_FROM_NAME="Documenso"

The sender address must be authorized to send from your email provider. Using an unauthorized address will cause delivery failures.

SMTP Configuration

SMTP is the most common email transport. Documenso supports two SMTP authentication methods.

SMTP with Username/Password (smtp-auth)

Use this for standard SMTP servers that authenticate with username and password.

Environment Variables:

VariableDescriptionDefault
NEXT_PRIVATE_SMTP_TRANSPORTSet to smtp-authsmtp-auth
NEXT_PRIVATE_SMTP_HOSTSMTP server hostname127.0.0.1
NEXT_PRIVATE_SMTP_PORTSMTP server port587
NEXT_PRIVATE_SMTP_USERNAMEAuthentication username
NEXT_PRIVATE_SMTP_PASSWORDAuthentication password
NEXT_PRIVATE_SMTP_SECUREUse TLS on connection (true or false)false
NEXT_PRIVATE_SMTP_UNSAFE_IGNORE_TLSDisable TLS entirely (not recommended)false
NEXT_PRIVATE_SMTP_SERVICENodemailer service preset (e.g., gmail)

Example Configuration:

NEXT_PRIVATE_SMTP_TRANSPORT="smtp-auth"
NEXT_PRIVATE_SMTP_HOST="smtp.example.com"
NEXT_PRIVATE_SMTP_PORT="587"
NEXT_PRIVATE_SMTP_USERNAME="your-username"
NEXT_PRIVATE_SMTP_PASSWORD="your-password"
NEXT_PRIVATE_SMTP_FROM_ADDRESS="noreply@example.com"
NEXT_PRIVATE_SMTP_FROM_NAME="Documenso"

Common SMTP Provider Examples

Gmail / Google Workspace:

NEXT_PRIVATE_SMTP_TRANSPORT="smtp-auth"
NEXT_PRIVATE_SMTP_HOST="smtp.gmail.com"
NEXT_PRIVATE_SMTP_PORT="587"
NEXT_PRIVATE_SMTP_USERNAME="your-email@gmail.com"
NEXT_PRIVATE_SMTP_PASSWORD="your-app-password"
NEXT_PRIVATE_SMTP_FROM_ADDRESS="your-email@gmail.com"
NEXT_PRIVATE_SMTP_FROM_NAME="Documenso"

Gmail requires an App Password when 2FA is enabled. Generate one at Google Account Security.

Microsoft 365 / Outlook:

NEXT_PRIVATE_SMTP_TRANSPORT="smtp-auth"
NEXT_PRIVATE_SMTP_HOST="smtp.office365.com"
NEXT_PRIVATE_SMTP_PORT="587"
NEXT_PRIVATE_SMTP_USERNAME="your-email@yourdomain.com"
NEXT_PRIVATE_SMTP_PASSWORD="your-password"
NEXT_PRIVATE_SMTP_FROM_ADDRESS="your-email@yourdomain.com"
NEXT_PRIVATE_SMTP_FROM_NAME="Documenso"

Amazon SES:

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-ses-smtp-username"
NEXT_PRIVATE_SMTP_PASSWORD="your-ses-smtp-password"
NEXT_PRIVATE_SMTP_FROM_ADDRESS="noreply@yourdomain.com"
NEXT_PRIVATE_SMTP_FROM_NAME="Documenso"

Postmark:

NEXT_PRIVATE_SMTP_TRANSPORT="smtp-auth"
NEXT_PRIVATE_SMTP_HOST="smtp.postmarkapp.com"
NEXT_PRIVATE_SMTP_PORT="587"
NEXT_PRIVATE_SMTP_USERNAME="your-postmark-server-api-token"
NEXT_PRIVATE_SMTP_PASSWORD="your-postmark-server-api-token"
NEXT_PRIVATE_SMTP_FROM_ADDRESS="noreply@yourdomain.com"
NEXT_PRIVATE_SMTP_FROM_NAME="Documenso"

SMTP with API Key (smtp-api)

Some providers use API key authentication instead of username/password. Use this transport for services like SendGrid.

Environment Variables:

VariableDescriptionDefault
NEXT_PRIVATE_SMTP_TRANSPORTSet to smtp-api
NEXT_PRIVATE_SMTP_HOSTSMTP server hostname
NEXT_PRIVATE_SMTP_PORTSMTP server port587
NEXT_PRIVATE_SMTP_APIKEY_USERAPI key usernameapikey
NEXT_PRIVATE_SMTP_APIKEYAPI key value
NEXT_PRIVATE_SMTP_SECUREUse TLS on connectionfalse

SendGrid Example:

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_ADDRESS="noreply@yourdomain.com"
NEXT_PRIVATE_SMTP_FROM_NAME="Documenso"

Resend Configuration

Resend provides a developer-friendly email API with excellent deliverability.

Environment Variables:

VariableDescription
NEXT_PRIVATE_SMTP_TRANSPORTSet to resend
NEXT_PRIVATE_RESEND_API_KEYYour Resend API key

Example Configuration:

NEXT_PRIVATE_SMTP_TRANSPORT="resend"
NEXT_PRIVATE_RESEND_API_KEY="re_xxxxxxxxxxxxxxxxxxxx"
NEXT_PRIVATE_SMTP_FROM_ADDRESS="noreply@yourdomain.com"
NEXT_PRIVATE_SMTP_FROM_NAME="Documenso"

Setup Steps:

Create an account

Sign up at resend.com.

Add and verify your sending domain

Configure your domain in the Resend dashboard so you can send from your own address.

Create an API key

Generate an API key in the Resend dashboard for Documenso to use.

Configure environment variables

Set the variables in the table above, including NEXT_PRIVATE_RESEND_API_KEY and your sender address.

MailChannels Configuration

MailChannels is an email delivery service often used with Cloudflare Workers.

Environment Variables:

VariableDescriptionDefault
NEXT_PRIVATE_SMTP_TRANSPORTSet to mailchannels
NEXT_PRIVATE_MAILCHANNELS_API_KEYAPI key for authentication
NEXT_PRIVATE_MAILCHANNELS_ENDPOINTCustom API endpoint (for proxy setups)https://api.mailchannels.net/tx/v1/send
NEXT_PRIVATE_MAILCHANNELS_DKIM_DOMAINDomain for DKIM signing
NEXT_PRIVATE_MAILCHANNELS_DKIM_SELECTORDKIM selector
NEXT_PRIVATE_MAILCHANNELS_DKIM_PRIVATE_KEYDKIM private key for signing

Example Configuration:

NEXT_PRIVATE_SMTP_TRANSPORT="mailchannels"
NEXT_PRIVATE_MAILCHANNELS_API_KEY="your-api-key"
NEXT_PRIVATE_SMTP_FROM_ADDRESS="noreply@yourdomain.com"
NEXT_PRIVATE_SMTP_FROM_NAME="Documenso"

With DKIM Signing:

NEXT_PRIVATE_SMTP_TRANSPORT="mailchannels"
NEXT_PRIVATE_MAILCHANNELS_API_KEY="your-api-key"
NEXT_PRIVATE_MAILCHANNELS_DKIM_DOMAIN="yourdomain.com"
NEXT_PRIVATE_MAILCHANNELS_DKIM_SELECTOR="mailchannels"
NEXT_PRIVATE_MAILCHANNELS_DKIM_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----\n...\n-----END RSA PRIVATE KEY-----"
NEXT_PRIVATE_SMTP_FROM_ADDRESS="noreply@yourdomain.com"
NEXT_PRIVATE_SMTP_FROM_NAME="Documenso"

Email Templates

Documenso uses React Email templates for all outgoing emails. The templates are located in packages/email/templates/ and include:

TemplatePurpose
document-invite.tsxSigning invitation sent to recipients
document-completed.tsxNotification when all parties have signed
document-pending.tsxReminder for pending signatures
document-cancel.tsxNotification when a document is cancelled
document-rejected.tsxNotification when a recipient rejects
confirm-email.tsxEmail verification for new accounts
forgot-password.tsxPassword reset request
reset-password.tsxPassword reset confirmation
organisation-invite.tsxTeam/organisation invitation

Branding Customization

Email templates support branding customization through organisation settings. When branding is enabled:

  • Custom logo replaces the Documenso logo
  • Branding colors are applied to email elements

Configure branding in the application under Organisation Settings > Preferences > Branding.

Template modifications require rebuilding the application. For simple customizations, use the branding settings instead.

Testing Email Delivery

Verify Configuration

Test your email configuration by creating an account or resetting a password. These actions trigger emails that confirm delivery is working.

Using a Test SMTP Server

For development or testing, use a local SMTP server like Mailhog or Mailpit:

# Using Docker
docker run -d -p 1025:1025 -p 8025:8025 mailhog/mailhog

Configure Documenso to use the test server:

NEXT_PRIVATE_SMTP_TRANSPORT="smtp-auth"
NEXT_PRIVATE_SMTP_HOST="localhost"
NEXT_PRIVATE_SMTP_PORT="1025"
NEXT_PRIVATE_SMTP_FROM_ADDRESS="test@localhost"
NEXT_PRIVATE_SMTP_FROM_NAME="Documenso Test"

View sent emails at http://localhost:8025.

Checking Logs

Email sending errors appear in the application logs. Check container or server logs for messages containing mailer or email:

# Docker
docker logs documenso 2>&1 | grep -i email

# Docker Compose
docker compose logs app 2>&1 | grep -i email

Email Deliverability

SPF Configuration

SPF (Sender Policy Framework) authorizes servers to send email for your domain. Add a TXT record to your DNS:

v=spf1 include:_spf.example.com ~all

Replace _spf.example.com with your email provider's SPF include. Common examples:

ProviderSPF Include
Gmailinclude:_spf.google.com
Microsoft 365include:spf.protection.outlook.com
SendGridinclude:sendgrid.net
Amazon SESinclude:amazonses.com
Resendinclude:_spf.resend.com
Postmarkinclude:spf.mtasv.net

DKIM Configuration

DKIM (DomainKeys Identified Mail) adds a digital signature to emails. Configuration varies by provider:

Generate DKIM keys

Create DKIM keys in your email provider's dashboard.

Add the TXT record to DNS

Add the provided TXT record to your DNS.

Enable DKIM signing

Enable DKIM signing in your provider settings.

For MailChannels, configure DKIM directly in Documenso using the environment variables described above.

DMARC Configuration

DMARC (Domain-based Message Authentication, Reporting, and Conformance) tells receiving servers how to handle emails that fail SPF or DKIM checks. Add a TXT record:

_dmarc.yourdomain.com  TXT  "v=DMARC1; p=quarantine; rua=mailto:dmarc@yourdomain.com"

DMARC policies:

PolicyBehavior
p=noneMonitor only, no action taken
p=quarantineMove failing emails to spam
p=rejectReject failing emails entirely

Start with p=none to monitor, then move to stricter policies once deliverability is confirmed.

Common Issues

See Also

On this page

Supported Email TransportsSender ConfigurationSMTP ConfigurationSMTP with Username/Password (smtp-auth)Common SMTP Provider ExamplesSMTP with API Key (smtp-api)Resend ConfigurationCreate an accountAdd and verify your sending domainCreate an API keyConfigure environment variablesMailChannels ConfigurationEmail TemplatesBranding CustomizationTesting Email DeliveryVerify ConfigurationUsing a Test SMTP ServerChecking LogsEmail DeliverabilitySPF ConfigurationDKIM ConfigurationGenerate DKIM keysAdd the TXT record to DNSEnable DKIM signingDMARC ConfigurationCommon IssuesSee Also