Email configuration

Configure outgoing SMTP email delivery in Redmine using config/configuration.yml.

Outgoing email delivery is configured in config/configuration.yml. Copy the example file before editing:

cp config/configuration.yml.example config/configuration.yml

Restart the application after any change to this file.

Do not configure SMTP settings in config/environment.rb. Use only config/configuration.yml.

Delivery methods

SMTP

Use the :smtp delivery method to send email through an SMTP server:

config/configuration.yml

default:
  email_delivery:
    delivery_method: :smtp
    smtp_settings:
      address: "mail.example.com"
      port: 25
      domain: "example.com"
      authentication: :login
      user_name: "[e-mail]"
      password: "your_password"

Sendmail

Use the :sendmail delivery method to deliver email via the local sendmail binary:

config/configuration.yml

default:
  email_delivery:
    delivery_method: :sendmail

Test (no delivery)

In development or staging environments you may want to collect emails without delivering them:

config/configuration.yml

development:
  email_delivery:
    delivery_method: :test

TLS and STARTTLS

STARTTLS (port 587)

Most modern SMTP providers support STARTTLS on port 587. Use enable_starttls_auto: true:

config/configuration.yml

default:
  email_delivery:
    delivery_method: :smtp
    smtp_settings:
      enable_starttls_auto: true
      address: "smtp.example.com"
      port: 587
      domain: "example.com"
      authentication: :plain
      user_name: "[e-mail]"
      password: "your_password"

SMTPS (implicit TLS, port 465)

For SMTPS (implicit TLS), use tls: true:

config/configuration.yml

default:
  email_delivery:
    delivery_method: :smtp
    smtp_settings:
      tls: true
      address: "smtp.example.com"
      port: 465
      domain: "example.com"
      authentication: :login
      user_name: "[e-mail]"
      password: "your_password"

Authentication methods

Value	Description
:plain	SMTP PLAIN authentication. Credentials are base64-encoded. Use only over TLS.
:login	SMTP LOGIN authentication. Similar to PLAIN. Use only over TLS.
:cram_md5	CRAM-MD5 challenge-response authentication. Credentials are not sent in plaintext.

Omit the authentication key entirely for unauthenticated relay (common for localhost SMTP).

Provider examples

Gmail

Gmail requires an App Password when using 2-step verification, or enabling “Less secure app access” for standard accounts.

config/configuration.yml

default:
  email_delivery:
    delivery_method: :smtp
    smtp_settings:
      enable_starttls_auto: true
      address: "smtp.gmail.com"
      port: 587
      domain: "smtp.gmail.com"
      authentication: :plain
      user_name: "[e-mail]"
      password: "your_app_password"

Local SMTP relay

For a local SMTP relay with no authentication:

config/configuration.yml

default:
  email_delivery:
    delivery_method: :smtp
    smtp_settings:
      address: "localhost"
      port: 25

Office 365

config/configuration.yml

default:
  email_delivery:
    delivery_method: :smtp
    smtp_settings:
      enable_starttls_auto: true
      address: "smtp.office365.com"
      port: 587
      domain: "yourdomain.com"
      authentication: :login
      user_name: "[e-mail]"
      password: "your_password"

SendGrid

config/configuration.yml

default:
  email_delivery:
    delivery_method: :smtp
    smtp_settings:
      enable_starttls_auto: true
      address: "smtp.sendgrid.net"
      port: 587
      domain: "yourdomain.com"
      authentication: :plain
      user_name: "apikey"
      password: "your_sendgrid_api_key"

SMTP settings reference

Key	Description
address	SMTP server hostname or IP address.
port	TCP port (commonly 25, 465, or 587).
domain	HELO domain sent to the SMTP server.
authentication	Authentication method: :plain, :login, or :cram_md5. Omit for no authentication.
user_name	SMTP username or email address.
password	SMTP password.
enable_starttls_auto	Enable opportunistic STARTTLS upgrade. Set to true for port 587.
tls	Use implicit TLS (SMTPS). Set to true for port 465.
openssl_verify_mode	TLS certificate verification: "none" or "peer" (default).

From address

The sender address for outgoing notifications is set in Administration → Settings → Email notifications:

Setting	Default	Description
mail_from	[e-mail]	From address used in all outgoing emails.
plain_text_mail	0	Send plain-text emails instead of HTML.

Per-environment configuration

config/configuration.yml supports separate blocks for each Rails environment. Settings in the production block override default settings in the production environment:

config/configuration.yml

default:
  email_delivery:
    delivery_method: :smtp
    smtp_settings:
      address: "smtp.example.com"
      port: 587
      enable_starttls_auto: true
      authentication: :plain
      user_name: "[e-mail]"
      password: "your_password"

production:
  # Overrides go here

development:
  email_delivery:
    delivery_method: :test