EmailConfiguration » History » Version 56

sceox x, 2022-07-31 18:11
update the configuration examples, "email_delivery" no longer exists

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