SMTP Configuration

By default, Formbricks doesn’t include an SMTP server for sending emails. However, you can easily configure your self-hosted instance to use your own email provider through environment variables.

Why Configure SMTP?

Setting up an SMTP server enables important email functionality in Formbricks, including:

Email verification for new accounts
Password reset emails
Team member invitation emails
Survey response notifications

Email Configuration Options

Formbricks uses Nodemailer to send emails and supports various SMTP providers like:

AWS SES
SendGrid
Mailgun
Gmail (for low volume)
Custom SMTP servers
Other SMTP providers

Required Environment Variables

To enable email functionality, configure the following environment variables:

# Basic SMTP Configuration
MAIL_FROM=[email protected]
MAIL_FROM_NAME=Formbricks
SMTP_HOST=smtp.yourprovider.com
SMTP_PORT=587
SMTP_USER=your_username
SMTP_PASSWORD=your_password

Additional optional settings:

# Enable SMTP_SECURE_ENABLED for TLS (port 465)
SMTP_SECURE_ENABLED=0

# If set to 0, the server won't require authentication
SMTP_AUTHENTICATED=1

# Verify the SMTP server certificate against trusted CAs (default and recommended)
SMTP_REJECT_UNAUTHORIZED_TLS=1

Do not set SMTP_REJECT_UNAUTHORIZED_TLS=0 in production. It disables SMTP server certificate verification and makes encrypted connections vulnerable to an active man-in-the-middle attack. If your SMTP server uses a private certificate authority, mount that CA certificate into the Formbricks container and add it to Node.js’ trust store instead.

Trusting A Private Certificate Authority

Store the CA certificate as a PEM file, mount it read-only, and set NODE_EXTRA_CA_CERTS to the path inside the container. Keep SMTP_REJECT_UNAUTHORIZED_TLS=1. For Docker Compose, add the following to the Formbricks service:

volumes:
  - ./certs/smtp-ca.pem:/etc/ssl/formbricks-ca/smtp-ca.pem:ro
environment:
  NODE_EXTRA_CA_CERTS: /etc/ssl/formbricks-ca/smtp-ca.pem
  SMTP_REJECT_UNAUTHORIZED_TLS: 1

For Kubernetes, create a ConfigMap containing the public CA certificate:

kubectl create configmap formbricks-smtp-ca \
  --from-file=smtp-ca.pem=./smtp-ca.pem \
  -n formbricks

Then mount it with the Helm chart:

deployment:
  env:
    NODE_EXTRA_CA_CERTS: /etc/ssl/formbricks-ca/smtp-ca.pem
    SMTP_REJECT_UNAUTHORIZED_TLS: "1"
  extraVolumes:
    - name: smtp-ca
      configMap:
        name: formbricks-smtp-ca
  extraVolumeMounts:
    - name: smtp-ca
      mountPath: /etc/ssl/formbricks-ca
      readOnly: true

Restart the Formbricks pods after changing the CA file because Node.js reads NODE_EXTRA_CA_CERTS when the process starts.

Enabling Email Features

By default, email verification and password reset features are disabled in Formbricks. To enable these features:

# Set to 0 to enable email verification (requires working SMTP)
EMAIL_VERIFICATION_DISABLED=0

# Set to 0 to enable password reset functionality (requires working SMTP)
PASSWORD_RESET_DISABLED=0

# Optional: configure the password reset link lifetime in minutes (5-120, default 30)
PASSWORD_RESET_TOKEN_LIFETIME_MINUTES=30

Configuration for One-Click Setup

If you’re using the one-click setup with Docker Compose, you can either:

Edit the docker-compose.yml file and add the SMTP environment variables:

environment:
  # Email Configuration
  MAIL_FROM: [email protected]
  MAIL_FROM_NAME: Formbricks
  SMTP_HOST: smtp.yourprovider.com
  SMTP_PORT: 587
  SMTP_USER: your_username
  SMTP_PASSWORD: your_password
  EMAIL_VERIFICATION_DISABLED: 0
  PASSWORD_RESET_DISABLED: 0
  PASSWORD_RESET_TOKEN_LIFETIME_MINUTES: 30

Or during the setup, answer “Yes” when prompted to set up the email service:

📧 Do you want to set up the email service? You will need SMTP credentials for the same! [y/N] y

Provider-Specific Examples

SendGrid

MAIL_FROM=[email protected]
MAIL_FROM_NAME=Formbricks
SMTP_HOST=smtp.sendgrid.net
SMTP_PORT=587
SMTP_USER=apikey
SMTP_PASSWORD=your_sendgrid_api_key

AWS SES

MAIL_FROM=[email protected]
MAIL_FROM_NAME=Formbricks
SMTP_HOST=email-smtp.us-east-1.amazonaws.com
SMTP_PORT=587
SMTP_USER=your_ses_access_key
SMTP_PASSWORD=your_ses_secret_key

Gmail

MAIL_FROM=[email protected]
MAIL_FROM_NAME=Formbricks
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=[email protected]
SMTP_PASSWORD=your_app_password

Note: For Gmail, you need to use an App Password if you have 2FA enabled.

Troubleshooting

If you’re experiencing issues with your email configuration:

Check that all required environment variables are set correctly
Verify your SMTP credentials are valid
Ensure your email provider allows sending from the specified MAIL_FROM address
If using Gmail, ensure you’re using an App Password
For secure connections, make sure you’ve set the correct port and SMTP_SECURE_ENABLED value

For additional help, join the conversation on GitHub Discussions.

Self Hosting

Setup

Configuration

Advanced

Why Configure SMTP?

Email Configuration Options

Required Environment Variables

Trusting A Private Certificate Authority

Enabling Email Features

Configuration for One-Click Setup

Provider-Specific Examples

SendGrid

AWS SES

Gmail

Troubleshooting

​Why Configure SMTP?

​Email Configuration Options

​Required Environment Variables

​Trusting A Private Certificate Authority

​Enabling Email Features

​Configuration for One-Click Setup

​Provider-Specific Examples

​SendGrid

​AWS SES

​Gmail

​Troubleshooting

Why Configure SMTP?

Email Configuration Options

Required Environment Variables

Trusting A Private Certificate Authority

Enabling Email Features

Configuration for One-Click Setup

Provider-Specific Examples

SendGrid

AWS SES

Gmail

Troubleshooting