Skip to content

Configuring outbound emails

In this guide we will describe how to configure outbound emails using an external SMTP server.


You will need to have SMTP settings ready. Those can either be from a company SMTP server, a Gmail account, or a public provider such as SendGrid.

Taking SendGrid as an example, you would need to sign up on their website (they offer a free plan with up to 12000 emails per month), and once your account is provisioned, generate a new API key and copy it somewhere (it looks like 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). You could also simply use your SendGrid username and password, but this is less secure.

You can adjust those settings for other SMTP providers, such as Gmail, Mandrill, etc. Please refer to the documentation of the corresponding provider to see what values should be used.

Configuration through the Admin UI

Nepenthes allows you to configure your SMTP settings through the administration UI. Using the default admin account created when you first installed Nepenthes, go to Administration > Emails and notifications.

At the bottom of this screen, you will find the following configuration form.


SMTP Options

These are the options that are available. Please see the Configuration guide and Environment variables guide on how to set these values from the command line.

OptionSettingENV nameDescription
Email delivery methodemail_delivery_methodNEPENTHES_EMAIL__DELIVERY__METHODemail delivery method to be used (smtp, sendmail)
SMTP serversmtp_addressNEPENTHES_SMTP__ADDRESSYour email SMTP server host name, for example:
SMTP portsmtp_portNEPENTHES_SMTP__PORTSMTP server port. Common options are 25 (plain) and 587 (SSL/TLS).
SMTP (HELO) domainsmtp_domainNEPENTHES_SMTP__DOMAINFully-qualified domain name of the SMTP client. This commonly will be the host name of the Nepenthes server.
SMTP authenticationsmtp_authenticationNEPENTHES_SMTP__AUTHENTICATIONAuthentication method, possible values: none, plain, login, cram_md5
SMTP user namesmtp_user_nameNEPENTHES_SMTP__USER__NAMEUser name for authentication against the SMTP server (when authentication is required)
SMTP passwordsmtp_passwordNEPENTHES_SMTP__PASSWORDPassword for authentication against the SMTP server (when authentication is required)
Automatically use STARTTLSsmtp_enable_starttls_autoNEPENTHES_SMTP__ENABLE__STARTTLS__AUTOYou can enable or disable STARTTLS here in case it doesn't work. Make sure you don't login to a SMTP server over a public network when using this. Recommended to leave this on if your server supports it. Possible values: true / false
OpenSSL verify modesmtp_openssl_verify_modeNEPENTHES_SMTP__OPENSSL__VERIFY__MODEDefine how the SMTP server certificate is validated. Make sure you don't just disable verification here unless both, Nepenthes and SMTP servers are on a private network. Possible values: none, peer, client_once or fail_if_no_peer_cert.
Note: This setting can only be set through ENV/settings

Package-based installation (DEB/RPM)

If you installed Nepenthes with the package-based installation, you can configure the above settings using the config:set helper. Please note that this will disable the settings in the administration UI.

openproject config:set NEPENTHES_EMAIL__DELIVERY__METHOD=smtp
openproject config:set
openproject config:set NEPENTHES_SMTP__PORT=587
openproject config:set
openproject config:set NEPENTHES_SMTP__AUTHENTICATION=login
openproject config:set NEPENTHES_SMTP__ENABLE__STARTTLS__AUTO=true
openproject config:set NEPENTHES_SMTP__USER_NAME="apikey"
openproject config:set NEPENTHES_SMTP__PASSWORD="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"

Docker installation

If you installed Nepenthes with Docker, here is how you would enable outbound emails through the use of the SMTP environment variables (with SendGrid, the SMTP_USER_NAME is always apikey. Just replace SMTP_PASSWORD with the API key you've generated and you should be good to go). Please note that this will disable the settings in the administration UI.

docker run -d \
  -e \
  -e \