EmailConfiguration » History » Version 45

Maxim Krušina, 2017-01-19 23:27

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 1 Cyber Sprocket
Valid settings:
28 34 Anonymous
* @:smtp@
29 34 Anonymous
* :@sendmail@
30 34 Anonymous
* @:async_smtp@
31 34 Anonymous
* @:async_sendmail@
32 1 Cyber Sprocket
33 6 Eric Davis
h4. Asynchronous delivery_methods
34 6 Eric Davis
35 30 Miodrag Milic
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 anti-spam feature, during which time synchronous method will block Redmine ("10 seconds":http://answers.bitnami.org/questions/4421/updating-an-issue-in-redmine-takes-10-seconds could be default value, see also #11376 for more information) .
36 1 Cyber Sprocket
37 23 Miodrag Milic
With this delivery method, smtp configuration is specified using @async_smtp_settings@ keyword:
38 23 Miodrag Milic
39 23 Miodrag Milic
<pre>
40 23 Miodrag Milic
development:
41 23 Miodrag Milic
  email_delivery:
42 23 Miodrag Milic
    delivery_method: :async_smtp
43 23 Miodrag Milic
    async_smtp_settings:
44 23 Miodrag Milic
    ...
45 23 Miodrag Milic
</pre>
46 23 Miodrag Milic
47 11 Etienne Massip
h2. Example configuration.yml Configurations
48 1 Cyber Sprocket
49 1 Cyber Sprocket
h3. Simple Login Authentication (default settings)
50 1 Cyber Sprocket
51 1 Cyber Sprocket
<pre>
52 1 Cyber Sprocket
# Outgoing email settings
53 1 Cyber Sprocket
54 1 Cyber Sprocket
production:
55 12 Ross Wilson
  email_delivery:
56 12 Ross Wilson
    delivery_method: :smtp
57 12 Ross Wilson
    smtp_settings:
58 12 Ross Wilson
      address: smtp.example.net
59 12 Ross Wilson
      port: 25
60 12 Ross Wilson
      domain: example.net
61 12 Ross Wilson
      authentication: :login
62 12 Ross Wilson
      user_name: redmine@example.net
63 12 Ross Wilson
      password: redmine
64 1 Cyber Sprocket
  
65 1 Cyber Sprocket
development:
66 12 Ross Wilson
  email_delivery:
67 12 Ross Wilson
    delivery_method: :smtp
68 12 Ross Wilson
    smtp_settings:
69 12 Ross Wilson
      address: 127.0.0.1
70 12 Ross Wilson
      port: 25
71 12 Ross Wilson
      domain: example.net
72 12 Ross Wilson
      authentication: :login
73 12 Ross Wilson
      user_name: redmine@example.net
74 12 Ross Wilson
      password: redmine
75 1 Cyber Sprocket
</pre>
76 1 Cyber Sprocket
77 44 Holger Just
h3. GMail, Google Apps
78 1 Cyber Sprocket
79 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:
80 8 Joël Lamotte
81 8 Joël Lamotte
<pre>
82 8 Joël Lamotte
production:
83 12 Ross Wilson
  email_delivery:
84 12 Ross Wilson
    delivery_method: :smtp
85 12 Ross Wilson
    smtp_settings:
86 12 Ross Wilson
      enable_starttls_auto: true
87 12 Ross Wilson
      address: "smtp.gmail.com" 
88 12 Ross Wilson
      port: '587'
89 12 Ross Wilson
      domain: "smtp.gmail.com" 
90 12 Ross Wilson
      authentication: :plain
91 1 Cyber Sprocket
      user_name: "your_email@gmail.com" 
92 1 Cyber Sprocket
      password: "your_password" 
93 1 Cyber Sprocket
</pre>
94 44 Holger Just
95 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.
96 45 Maxim Krušina
More information and detailed guide how to enable SMTP relay is here: https://support.google.com/a/answer/2956491
97 45 Maxim Krušina
And config can be really simple:
98 45 Maxim Krušina
99 45 Maxim Krušina
<pre>
100 45 Maxim Krušina
production:
101 45 Maxim Krušina
  email_delivery:
102 45 Maxim Krušina
    delivery_method: :smtp
103 45 Maxim Krušina
    smtp_settings:
104 45 Maxim Krušina
      address: smtp-relay.gmail.com
105 45 Maxim Krušina
      port: 587
106 45 Maxim Krušina
      domain: smtp-relay.gmail.com
107 45 Maxim Krušina
      authentication: :plain
108 45 Maxim Krušina
      user_name: your_email@gmail.com
109 45 Maxim Krušina
      password: your_password
110 45 Maxim Krušina
</pre>
111 45 Maxim Krušina
112 45 Maxim Krušina
113 44 Holger Just
h3. Office 365, Exchange Online
114 8 Joël Lamotte
115 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.
116 41 Pierre Maigne
117 41 Pierre Maigne
<pre>
118 41 Pierre Maigne
production:
119 41 Pierre Maigne
  email_delivery:
120 41 Pierre Maigne
    delivery_method: :smtp
121 41 Pierre Maigne
    smtp_settings:
122 41 Pierre Maigne
      enable_starttls_auto: true
123 41 Pierre Maigne
      address: "smtp.office365.com"
124 41 Pierre Maigne
      port: '587'
125 41 Pierre Maigne
      domain: "your_domain.com"
126 41 Pierre Maigne
      authentication: :login
127 41 Pierre Maigne
      user_name: "email@your_domain.com"
128 41 Pierre Maigne
      password: "password"
129 41 Pierre Maigne
</pre>
130 41 Pierre Maigne
131 8 Joël Lamotte
However, this will only work with "recent" enough ruby and rails versions (1.8.7 patchset 2xx and 2.3.5).
132 8 Joël Lamotte
(See #5814 )
133 8 Joël Lamotte
134 1 Cyber Sprocket
h3. No Authentication
135 1 Cyber Sprocket
136 34 Anonymous
Example for an SMTP service provider with no authentication.
137 1 Cyber Sprocket
138 1 Cyber Sprocket
<pre>
139 13 Ross Wilson
production:
140 13 Ross Wilson
  email_delivery:
141 13 Ross Wilson
    delivery_method: :smtp
142 13 Ross Wilson
    smtp_settings:
143 13 Ross Wilson
      address: smtp.knology.net
144 13 Ross Wilson
      port: 25
145 13 Ross Wilson
      domain: cybersprocket.com
146 1 Cyber Sprocket
</pre>
147 1 Cyber Sprocket
148 1 Cyber Sprocket
h3. Using sendmail command
149 5 Eric Davis
150 5 Eric Davis
Example for a unix system that uses the @/usr/sbin/sendmail@ command.
151 5 Eric Davis
152 5 Eric Davis
<pre>
153 5 Eric Davis
production:
154 13 Ross Wilson
  email_delivery:
155 13 Ross Wilson
    delivery_method: :sendmail
156 5 Eric Davis
</pre>
157 1 Cyber Sprocket
158 35 Jean-Baptiste Barth
h2. Troubleshooting
159 35 Jean-Baptiste Barth
160 35 Jean-Baptiste Barth
h3. Error: "hostname was not match with the server certificate"
161 35 Jean-Baptiste Barth
162 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:
163 35 Jean-Baptiste Barth
164 35 Jean-Baptiste Barth
    enable_starttls_auto: false
165 35 Jean-Baptiste Barth
166 36 Richard Gomes
h3. Error: "Mail failure - no recipient addresses"
167 36 Richard Gomes
168 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.
169 36 Richard Gomes
170 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.
171 36 Richard Gomes
172 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:
173 36 Richard Gomes
174 36 Richard Gomes
<pre>
175 36 Richard Gomes
# default configuration options for all environments
176 36 Richard Gomes
default:
177 36 Richard Gomes
  email_delivery:    
178 36 Richard Gomes
    delivery_method: :sendmail
179 36 Richard Gomes
    sendmail_settings:
180 36 Richard Gomes
      arguments: "-i" 
181 36 Richard Gomes
</pre>
182 36 Richard Gomes
183 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.
184 38 Richard Gomes
185 43 hongbo yang
h3. Error: "Timeout:Error" due to SSL SMTP server connection
186 43 hongbo yang
187 1 Cyber Sprocket
add an ssl option to the configuration.yml #17239
188 43 hongbo yang
189 42 hongbo yang
<pre>
190 42 hongbo yang
default:
191 42 hongbo yang
  # Outgoing emails configuration (see examples above)
192 42 hongbo yang
  email_delivery:
193 42 hongbo yang
    delivery_method: :smtp
194 42 hongbo yang
  smtp_settings:
195 42 hongbo yang
    address: smtp.domain.com
196 42 hongbo yang
    port: 465
197 42 hongbo yang
    ssl: true
198 42 hongbo yang
    enable_starttls_auto: true
199 42 hongbo yang
    domain: domain.com
200 42 hongbo yang
    authentication: :login
201 42 hongbo yang
    user_name: redmine@domain.com
202 42 hongbo yang
    password: xxxx
203 42 hongbo yang
</pre>
204 42 hongbo yang
205 7 Mischa The Evil
h2. More information
206 5 Eric Davis
207 5 Eric Davis
* "Action Mailer Configuration":http://guides.rubyonrails.org/action_mailer_basics.html#action-mailer-configuration