EmailConfiguration » History » Version 55

Liane Hampe, 2021-10-16 14:58
Add note w.r.t. to deprecated async_smtp and async_sendmail settings since Redmine version 4.0

1 1 Cyber Sprocket
h1. Email Configuration
2 1 Cyber Sprocket
3 7 Mischa The Evil
{{>toc}}
4 7 Mischa The Evil
5 31 Miodrag Milic
6 1 Cyber Sprocket
h2. Configuration Directives
7 1 Cyber Sprocket
8 34 Anonymous
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
9 34 Anonymous
for detailed information.
10 1 Cyber Sprocket
11 1 Cyber Sprocket
h3. authentication
12 1 Cyber Sprocket
13 1 Cyber Sprocket
The type of authentication method expected by your service provider. 
14 1 Cyber Sprocket
15 1 Cyber Sprocket
Valid settings:
16 34 Anonymous
* @nil@ (or omit the key) for no authentication
17 34 Anonymous
* @:plain@
18 34 Anonymous
* @:login@
19 34 Anonymous
* @:cram_md5@
20 1 Cyber Sprocket
21 34 Anonymous
(note: if you set this to @nil@ or omit it, you must not include the @user_name@ and @password@ settings)
22 1 Cyber Sprocket
23 1 Cyber Sprocket
h3. delivery_method
24 1 Cyber Sprocket
25 6 Eric Davis
The mail transport method to be used.
26 1 Cyber Sprocket
27 54 Ben Blanco
Valid settings (=< Redmine v3.x):
28 34 Anonymous
* @:smtp@
29 34 Anonymous
* :@sendmail@
30 34 Anonymous
* @:async_smtp@
31 1 Cyber Sprocket
* @:async_sendmail@
32 54 Ben Blanco
33 54 Ben Blanco
Valid settings (>= Redmine v4.x; cf. #30068):
34 54 Ben Blanco
* @:smtp@
35 54 Ben Blanco
* :@sendmail@
36 1 Cyber Sprocket
37 6 Eric Davis
h4. Asynchronous delivery_methods
38 6 Eric Davis
39 52 Go MAEDA
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).
40 1 Cyber Sprocket
41 52 Go MAEDA
With this delivery method, smtp configuration is specified using @async_smtp_settings@ keyword instead of @smtp_settings@ keyword:
42 23 Miodrag Milic
43 47 Toshi MARUYAMA
<pre><code class="yml">
44 23 Miodrag Milic
development:
45 1 Cyber Sprocket
  email_delivery:
46 1 Cyber Sprocket
    delivery_method: :async_smtp
47 52 Go MAEDA
    async_smtp_settings:  # Don't use "smtp_settings"
48 52 Go MAEDA
      address: ...
49 52 Go MAEDA
      port: ...
50 52 Go MAEDA
      ...
51 47 Toshi MARUYAMA
</code></pre>
52 23 Miodrag Milic
53 55 Liane Hampe
> *Please note:* Since Redmine 4.0 asynchronous email sending is removed in favour of Rails ActiveJob module which sends emails asynchronously.See https://www.redmine.org/projects/redmine/repository/entry/tags/4.0.0/lib/redmine/configuration.rb#L53 for more details.
54 55 Liane Hampe
55 11 Etienne Massip
h2. Example configuration.yml Configurations
56 1 Cyber Sprocket
57 1 Cyber Sprocket
h3. Simple Login Authentication (default settings)
58 1 Cyber Sprocket
59 47 Toshi MARUYAMA
<pre><code class="yml">
60 1 Cyber Sprocket
# Outgoing email settings
61 1 Cyber Sprocket
62 1 Cyber Sprocket
production:
63 12 Ross Wilson
  email_delivery:
64 12 Ross Wilson
    delivery_method: :smtp
65 12 Ross Wilson
    smtp_settings:
66 12 Ross Wilson
      address: smtp.example.net
67 12 Ross Wilson
      port: 25
68 12 Ross Wilson
      domain: example.net
69 12 Ross Wilson
      authentication: :login
70 12 Ross Wilson
      user_name: redmine@example.net
71 12 Ross Wilson
      password: redmine
72 1 Cyber Sprocket
  
73 1 Cyber Sprocket
development:
74 12 Ross Wilson
  email_delivery:
75 12 Ross Wilson
    delivery_method: :smtp
76 12 Ross Wilson
    smtp_settings:
77 12 Ross Wilson
      address: 127.0.0.1
78 12 Ross Wilson
      port: 25
79 12 Ross Wilson
      domain: example.net
80 12 Ross Wilson
      authentication: :login
81 12 Ross Wilson
      user_name: redmine@example.net
82 12 Ross Wilson
      password: redmine
83 47 Toshi MARUYAMA
</code></pre>
84 1 Cyber Sprocket
85 44 Holger Just
h3. GMail, Google Apps
86 1 Cyber Sprocket
87 44 Holger Just
If you want to use GMail/Google Apps and other TLS-requiring SMTP servers, you'll have to add some TLS-related settings:
88 8 Joël Lamotte
89 47 Toshi MARUYAMA
<pre><code class="yml">
90 8 Joël Lamotte
production:
91 12 Ross Wilson
  email_delivery:
92 12 Ross Wilson
    delivery_method: :smtp
93 12 Ross Wilson
    smtp_settings:
94 12 Ross Wilson
      enable_starttls_auto: true
95 12 Ross Wilson
      address: "smtp.gmail.com" 
96 51 Go MAEDA
      port: 587
97 12 Ross Wilson
      domain: "smtp.gmail.com" 
98 12 Ross Wilson
      authentication: :plain
99 1 Cyber Sprocket
      user_name: "your_email@gmail.com" 
100 1 Cyber Sprocket
      password: "your_password" 
101 47 Toshi MARUYAMA
</code></pre>
102 44 Holger Just
103 45 Maxim Krušina
When sending from G Suite (formerly Google Apps), it's good to use *SMTP relay* which has much larger sending limits.
104 45 Maxim Krušina
More information and detailed guide how to enable SMTP relay is here: https://support.google.com/a/answer/2956491
105 46 Maxim Krušina
When configuring SMTP relay service use something like this:
106 46 Maxim Krušina
* Name: Redmine
107 46 Maxim Krušina
* 1. Allowed senders:
108 46 Maxim Krušina
** Only registered Apps users in my domains - in case You have created dedicated G Suite user for Redmine
109 46 Maxim Krušina
* 2. Authentication
110 46 Maxim Krušina
** [x] Only accept mail from the specified IP addresses - IP address of your Redmine server
111 46 Maxim Krušina
** [x] Require SMTP Authentication
112 46 Maxim Krušina
* 3. Encryption
113 46 Maxim Krušina
** [x] Require TLS encryption
114 46 Maxim Krušina
115 45 Maxim Krušina
And config can be really simple:
116 45 Maxim Krušina
117 47 Toshi MARUYAMA
<pre><code class="yml">
118 45 Maxim Krušina
production:
119 45 Maxim Krušina
  email_delivery:
120 45 Maxim Krušina
    delivery_method: :smtp
121 45 Maxim Krušina
    smtp_settings:
122 45 Maxim Krušina
      address: smtp-relay.gmail.com
123 45 Maxim Krušina
      port: 587
124 45 Maxim Krušina
      domain: smtp-relay.gmail.com
125 45 Maxim Krušina
      authentication: :plain
126 45 Maxim Krušina
      user_name: your_email@gmail.com
127 45 Maxim Krušina
      password: your_password
128 47 Toshi MARUYAMA
</code></pre>
129 45 Maxim Krušina
130 44 Holger Just
h3. Office 365, Exchange Online
131 8 Joël Lamotte
132 41 Pierre Maigne
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.
133 41 Pierre Maigne
134 47 Toshi MARUYAMA
<pre><code class="yml">
135 41 Pierre Maigne
production:
136 41 Pierre Maigne
  email_delivery:
137 41 Pierre Maigne
    delivery_method: :smtp
138 41 Pierre Maigne
    smtp_settings:
139 41 Pierre Maigne
      enable_starttls_auto: true
140 41 Pierre Maigne
      address: "smtp.office365.com"
141 51 Go MAEDA
      port: 587
142 41 Pierre Maigne
      domain: "your_domain.com"
143 41 Pierre Maigne
      authentication: :login
144 41 Pierre Maigne
      user_name: "email@your_domain.com"
145 41 Pierre Maigne
      password: "password"
146 47 Toshi MARUYAMA
</code></pre>
147 41 Pierre Maigne
148 8 Joël Lamotte
149 1 Cyber Sprocket
h3. No Authentication
150 1 Cyber Sprocket
151 34 Anonymous
Example for an SMTP service provider with no authentication.
152 1 Cyber Sprocket
153 47 Toshi MARUYAMA
<pre><code class="yml">
154 13 Ross Wilson
production:
155 13 Ross Wilson
  email_delivery:
156 13 Ross Wilson
    delivery_method: :smtp
157 13 Ross Wilson
    smtp_settings:
158 13 Ross Wilson
      address: smtp.knology.net
159 13 Ross Wilson
      port: 25
160 13 Ross Wilson
      domain: cybersprocket.com
161 47 Toshi MARUYAMA
</code></pre>
162 1 Cyber Sprocket
163 1 Cyber Sprocket
h3. Using sendmail command
164 5 Eric Davis
165 5 Eric Davis
Example for a unix system that uses the @/usr/sbin/sendmail@ command.
166 5 Eric Davis
167 47 Toshi MARUYAMA
<pre><code class="yml">
168 5 Eric Davis
production:
169 13 Ross Wilson
  email_delivery:
170 13 Ross Wilson
    delivery_method: :sendmail
171 47 Toshi MARUYAMA
</code></pre>
172 1 Cyber Sprocket
173 35 Jean-Baptiste Barth
h2. Troubleshooting
174 35 Jean-Baptiste Barth
175 35 Jean-Baptiste Barth
h3. Error: "hostname was not match with the server certificate"
176 35 Jean-Baptiste Barth
177 35 Jean-Baptiste Barth
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:
178 35 Jean-Baptiste Barth
179 48 Toshi MARUYAMA
<pre><code class="yml">
180 35 Jean-Baptiste Barth
    enable_starttls_auto: false
181 48 Toshi MARUYAMA
</code></pre>
182 35 Jean-Baptiste Barth
183 53 Lloyd Su
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:
184 53 Lloyd Su
185 53 Lloyd Su
<pre><code class="yml">
186 53 Lloyd Su
    openssl_verify_mode: "NONE"
187 53 Lloyd Su
</code></pre>
188 53 Lloyd Su
189 36 Richard Gomes
h3. Error: "Mail failure - no recipient addresses"
190 36 Richard Gomes
191 36 Richard Gomes
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.
192 36 Richard Gomes
193 39 Richard Gomes
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.
194 36 Richard Gomes
195 37 Richard Gomes
The solution consists on editing your _config/configuration.yml_ and making sure you define @arguments@ containing the string @"-i"@, as shown below:
196 36 Richard Gomes
197 47 Toshi MARUYAMA
<pre><code class="yml">
198 36 Richard Gomes
# default configuration options for all environments
199 36 Richard Gomes
default:
200 36 Richard Gomes
  email_delivery:    
201 36 Richard Gomes
    delivery_method: :sendmail
202 36 Richard Gomes
    sendmail_settings:
203 36 Richard Gomes
      arguments: "-i" 
204 47 Toshi MARUYAMA
</code></pre>
205 36 Richard Gomes
206 40 Richard Gomes
The example above employs @:sendmail@ method, which employs @sendmail_settings@. In case you are using @:smtp@ or @:async_smtp@ methods, try @smtp_settings@ instead.
207 38 Richard Gomes
208 43 hongbo yang
h3. Error: "Timeout:Error" due to SSL SMTP server connection
209 43 hongbo yang
210 1 Cyber Sprocket
add an ssl option to the configuration.yml #17239
211 43 hongbo yang
212 47 Toshi MARUYAMA
<pre><code class="yml">
213 42 hongbo yang
default:
214 42 hongbo yang
  # Outgoing emails configuration (see examples above)
215 42 hongbo yang
  email_delivery:
216 42 hongbo yang
    delivery_method: :smtp
217 42 hongbo yang
  smtp_settings:
218 42 hongbo yang
    address: smtp.domain.com
219 42 hongbo yang
    port: 465
220 42 hongbo yang
    ssl: true
221 42 hongbo yang
    enable_starttls_auto: true
222 42 hongbo yang
    domain: domain.com
223 42 hongbo yang
    authentication: :login
224 42 hongbo yang
    user_name: redmine@domain.com
225 42 hongbo yang
    password: xxxx
226 47 Toshi MARUYAMA
</code></pre>
227 42 hongbo yang
228 7 Mischa The Evil
h2. More information
229 5 Eric Davis
230 5 Eric Davis
* "Action Mailer Configuration":http://guides.rubyonrails.org/action_mailer_basics.html#action-mailer-configuration