Alertmanager: Improving the docs for email config?

[estechnical]

I thought since I was still having only limited success with alertmanager sending emails, I should check whether I'm doing it right, and at the same time try and get something up here for others to copy from until the docs are the definitive source of info...

Reading from various articles about the SMTP AUTH world, including https://www.fastmail.com/help/technical/ssltlsstarttls.html, I concluded that the likely combinations are:

Example config for TLS email server:

global:
  smtp_smarthost: 'xxxx.com:578'
  smtp_from: '[email protected]'
  smtp_auth_identity: '[email protected]'
  smtp_auth_secret: 'nnnnnnnn'

Example config for SSL email server:

global:
  smtp_smarthost: 'xxxx.com:465'
  smtp_from: '[email protected]'
  smtp_auth_username: '[email protected]'
  smtp_auth_password: 'nnnnnnnnnn'

Example config for plain SMTP email server:

global:
  smtp_smarthost: 'xxxx.com:25'
  smtp_from: '[email protected]'

Example config for SMTP with auth:

global:
  smtp_smarthost: 'xxxx.com:25'
  smtp_from: '[email protected]'
  smtp_auth_username: '[email protected]'
  smtp_auth_password: 'nnnnnnnnnn'

Then a simple email receiver config:

receivers:
- name: 'mail'
 email_configs:
 - to: '[email protected]'
   send_resolved: true
   require_tls: false
 - to: '[email protected]'
   send_resolved: true
   require_tls: false

Please correct me if anything is wrong, I'll edit the config snippets - I'm not sure if I've missed any options.

Where do smtp_auth_identity and smtp_auth_secret fit into the above configs? Are there more permutations than those I have listed?

I have received errors like WARN[0600] Notify attempt 1 failed: EOF source=notify.go:193 when it tries to send the email. I think this sort of error, once we know the reason for it should be caught and a useful error message printed...

I'm happy to try and fix docs and code, but I'm not an expert in email or go!

Thanks in advance to anyone who can help!

[estechnical]

I updated the example configs a bit, I have now successfully sent emails from alertmanager using the SMTP with auth config above. I have had issues with TLS/SSL emails as the error reporting is almost nonexistent.

[RajatNair]

@estechnical - are you sure

global:
  smtp_require_tls: false

works?

In latest prom/alertmanager image from Docker Hub, this setting did not work. Instead adding this setting as part of email config worked -

email_configs:
    - to: '[email protected]'
      require_tls: false

[beorn7]

Indeed, there is no global TLS option. See #433

[estechnical]

I have updated the config snippets in my post according to these suggestions. Thanks :)

[michaelyangwj]

Indeed,a more detail doc is necessary.

[allenbang]

DEBU[0122] Notify attempt 2 failed: EOF source=notify.go:546
ERRO[0122] Error on notify: EOF
I think it make users feel confused. It's better to have more certain error.

[civik]

@estechnical you're my f'n hero with the 'require_tls: false'. Wasted a day because that flag seems to not be documented ANYWHERE.

[estechnical]

I notice the "help wanted" tag... how would I help? :)

[mxinden]

@estechnical could you extend the existing email_config documentation in the Promtheus documentation? You can find the repository here.

[bjoernhaeuser]

I started to work on this: prometheus/docs#917

[vietthang207]

Hello all. I have a question related to this config but the docs is not clear enough. How can I send to multiple email, I've tried some format of the but they didn't work:

1. 
   to: [email protected],[email protected]
   2.
   to: [email protected]
   to: [email protected]
   3.
   to: [email protected]
   [email protected]
   4.
   to:
   
   
   
   • [email protected]
   
   
   • [email protected]
     
     5.
     
     to: [[email protected], [email protected]]
   
   

Or it is just not possible to send to multiple email address at once. Thanks in advance!

[mxinden]

@vietthang207 you should just be able to separate them by comma:

receivers:
- name: 'email'
  email_configs:
  - to: [email protected], [email protected]

For better debugging of the email provider make sure to start Alertmanager with the --log.level=debug flag. As a test server you can use sudo python -m smtpd -n -c DebuggingServer 192.168.2.118:25 in case you have python installed.

In general, please open up usage questions on the [email protected] mailing list.