Project

General

Profile

EmailConfiguration » History » Revision 54

Revision 53 (Lloyd Su, 2019-11-12 17:06) → Revision 54/57 (Ben Blanco, 2020-03-23 15:47)

h1. Email Configuration 

 {{>toc}} 


 h2. Configuration Directives 

 This page is a work in progress, the following configuration directives are only a partial list. Please consult "Action Mailer Configuration":http://guides.rubyonrails.org/action_mailer_basics.html#action-mailer-configuration 
 for detailed information. 

 h3. 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) 

 h3. delivery_method 

 The mail transport method to be used. 

 Valid settings (=< Redmine v3.x): settings: 
 * @:smtp@ 
 * :@sendmail@ 
 * @:async_smtp@ 
 * @:async_sendmail@ 

 Valid settings (>= Redmine v4.x; cf. #30068): 
 * @:smtp@ 
 * :@sendmail@ 

 h4. 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":http://redmineblog.com/articles/asynchronous-email-delivery/ for more details. Some SMTP servers have delay period before processing takes place as an anti-spam feature, during which time synchronous method will block Redmine ("10 seconds":https://community.bitnami.com/t/updating-an-issue-in-redmine-takes-10-seconds/4421 could be a default value, see also #11376 for more information). 

 With this delivery method, smtp configuration is specified using @async_smtp_settings@ keyword instead of @smtp_settings@ keyword: 

 <pre><code class="yml"> 
 development: 
   email_delivery: 
     delivery_method: :async_smtp 
     async_smtp_settings:    # Don't use "smtp_settings" 
       address: ... 
       port: ... 
       ... 
 </code></pre> 

 h2. Example configuration.yml Configurations 

 h3. Simple Login Authentication (default settings) 

 <pre><code class="yml"> 
 # 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 
 </code></pre> 

 h3. 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: 

 <pre><code class="yml"> 
 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"  
 </code></pre> 

 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 
 When configuring SMTP relay service use something like this: 
 * Name: Redmine 
 * 1. Allowed senders: 
 ** Only registered Apps users in my domains - in case You have created dedicated G Suite user for Redmine 
 * 2. Authentication 
 ** [x] Only accept mail from the specified IP addresses - IP address of your Redmine server 
 ** [x] Require SMTP Authentication 
 * 3. Encryption 
 ** [x] Require TLS encryption 

 And config can be really simple: 

 <pre><code class="yml"> 
 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 
 </code></pre> 

 h3. 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. 

 <pre><code class="yml"> 
 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" 
 </code></pre> 


 h3. No Authentication 

 Example for an SMTP service provider with no authentication. 

 <pre><code class="yml"> 
 production: 
   email_delivery: 
     delivery_method: :smtp 
     smtp_settings: 
       address: smtp.knology.net 
       port: 25 
       domain: cybersprocket.com 
 </code></pre> 

 h3. Using sendmail command 

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

 <pre><code class="yml"> 
 production: 
   email_delivery: 
     delivery_method: :sendmail 
 </code></pre> 

 h2. Troubleshooting 

 h3. 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: 

 <pre><code class="yml"> 
     enable_starttls_auto: false 
 </code></pre> 

 If you have to enable starttls and just want to bypass the certificate verification, you can add following option in the appropriate "email_delivery" section: 

 <pre><code class="yml"> 
     openssl_verify_mode: "NONE" 
 </code></pre> 

 h3. 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: 

 <pre><code class="yml"> 
 # default configuration options for all environments 
 default: 
   email_delivery:     
     delivery_method: :sendmail 
     sendmail_settings: 
       arguments: "-i"  
 </code></pre> 

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

 h3. Error: "Timeout:Error" due to SSL SMTP server connection 

 add an ssl option to the configuration.yml #17239 

 <pre><code class="yml"> 
 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 
 </code></pre> 

 h2. More information 

 * "Action Mailer Configuration":http://guides.rubyonrails.org/action_mailer_basics.html#action-mailer-configuration