Email Configuration¶

• Table of contents
• Email Configuration
  • Configuration Directives
    • authentication
    • delivery_method
      • Asynchronous delivery_methods
  • Example configuration.yml Configurations
    • Simple Login Authentication (default settings)
    • GMail, Google Apps
    • Office 365, Exchange Online
    • No Authentication
    • Using sendmail command
  • Troubleshooting
    • Error: "hostname was not match with the server certificate"
    • Error: "Mail failure - no recipient addresses"
    • Error: "Timeout:Error" due to SSL SMTP server connection
  • More information

Configuration Directives¶

This page is a work in progress, the following configuration directives are only a partial list. Please consult Action Mailer Configuration
for detailed information.

authentication¶

The type of authentication method expected by your service provider.

Valid settings:

• nil (or omit the key) for no authentication
• :plain
• :login
• :cram_md5

(note: if you set this to nil or omit it, you must not include the user_name and password settings)

delivery_method¶

The mail transport method to be used.

Valid settings:

• :smtp
• :sendmail
• :async_smtp
• :async_sendmail

Asynchronous delivery_methods¶

The :async_smtp and :async_sendmail use asynchronous sends, which means Redmine does not wait for the email to be sent to display the next page. See Asynchronous Email Delivery for more details. Some SMTP servers have delay period before processing takes place as anti-spam feature, during which time synchronous method will block Redmine (10 seconds could be default value, see also #11376 for more information) .

With this delivery method, smtp configuration is specified using async_smtp_settings keyword:

development:
  email_delivery:
    delivery_method: :async_smtp
    async_smtp_settings:
    ...

Example configuration.yml Configurations¶

Simple Login Authentication (default settings)¶

# Outgoing email settings

production:
  email_delivery:
    delivery_method: :smtp
    smtp_settings:
      address: smtp.example.net
      port: 25
      domain: example.net
      authentication: :login
      user_name: redmine@example.net
      password: redmine

development:
  email_delivery:
    delivery_method: :smtp
    smtp_settings:
      address: 127.0.0.1
      port: 25
      domain: example.net
      authentication: :login
      user_name: redmine@example.net
      password: redmine

GMail, Google Apps¶

If you want to use GMail/Google Apps and other TLS-requiring SMTP servers, you'll have to add some TLS-related settings:

production:
  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: "your_email@gmail.com" 
      password: "your_password" 

When sending from G Suite (formerly Google Apps), it's good to use SMTP relay which has much larger sending limits.
More information and detailed guide how to enable SMTP relay is here: https://support.google.com/a/answer/2956491
And config can be really simple:

production:
  email_delivery:
    delivery_method: :smtp
    smtp_settings:
      address: smtp-relay.gmail.com
      port: 587
      domain: smtp-relay.gmail.com
      authentication: :plain
      user_name: your_email@gmail.com
      password: your_password

Office 365, Exchange Online¶

Here is an example for Office 365 users (Exchange online). The sender must have an account, or if you want to send from a shared mailbox, the account below must have authorization to "Send As" the sender which is defined in Redmine email notifications settings.

production:
  email_delivery:
    delivery_method: :smtp
    smtp_settings:
      enable_starttls_auto: true
      address: "smtp.office365.com" 
      port: '587'
      domain: "your_domain.com" 
      authentication: :login
      user_name: "email@your_domain.com" 
      password: "password" 

However, this will only work with "recent" enough ruby and rails versions (1.8.7 patchset 2xx and 2.3.5).
(See #5814 )

No Authentication¶

Example for an SMTP service provider with no authentication.

production:
  email_delivery:
    delivery_method: :smtp
    smtp_settings:
      address: smtp.knology.net
      port: 25
      domain: cybersprocket.com

Using sendmail command¶

Example for a unix system that uses the /usr/sbin/sendmail command.

production:
  email_delivery:
    delivery_method: :sendmail

Troubleshooting¶

Error: "hostname was not match with the server certificate"¶

If you get this error, there's probably a problem verifying the SSL certificate of your smtp relay. As a temporary fix, you can set this option in the appropriate "email_delivery" section:

enable_starttls_auto: false

Error: "Mail failure - no recipient addresses"¶

When this error happens, the notification is not delivered to the destination address. Instead, you will probably receive a rejection message on your sender address, where you can see the header of the message sent, containing "From:" fields but not containing any "To:" fields.

This error is common on Debian boxes, due to the way exim4 is configured by default, which is "-i -t". This configuration tells exim4 that the destination address is inside the header of the message. Instead, we need to configure exim4 so that the destination address will be retrieved from the command line.

The solution consists on editing your config/configuration.yml and making sure you define arguments containing the string "-i", as shown below:

# default configuration options for all environments
default:
  email_delivery:    
    delivery_method: :sendmail
    sendmail_settings:
      arguments: "-i" 

The example above employs :sendmail method, which employs sendmail_settings. In case you are using :smtp or :async_smtp methods, try smtp_settings instead.

Error: "Timeout:Error" due to SSL SMTP server connection¶

add an ssl option to the configuration.yml #17239

default:
  # Outgoing emails configuration (see examples above)
  email_delivery:
    delivery_method: :smtp
  smtp_settings:
    address: smtp.domain.com
    port: 465
    ssl: true
    enable_starttls_auto: true
    domain: domain.com
    authentication: :login
    user_name: redmine@domain.com
    password: xxxx

More information¶

• Action Mailer Configuration