diff --git a/development.ini b/development.ini
--- a/development.ini
+++ b/development.ini
@@ -55,17 +55,16 @@ pdebug = false
 #error_email_from = paste_error@example.com
 
 ## SMTP server settings
-## Only smtp_server is mandatory. All other settings take the specified default
-## values.
+## If specifying credentials, make sure to use secure connections.
+## Default: Send unencrypted unauthenticated mails to the specified smtp_server.
+## For "SSL", use smtp_use_ssl = true and smtp_port = 465.
+## For "STARTTLS", use smtp_use_tls = true and smtp_port = 587.
 #smtp_server = smtp.example.com
 #smtp_username =
 #smtp_password =
 #smtp_port = 25
+#smtp_use_ssl = false
 #smtp_use_tls = false
-#smtp_use_ssl = false
-## SMTP authentication parameters to use (e.g. LOGIN PLAIN CRAM-MD5, etc.).
-## If empty, use any of the authentication parameters supported by the server.
-#smtp_auth =
 
 [server:main]
 ## PASTE ##
diff --git a/docs/usage/email.rst b/docs/usage/email.rst
--- a/docs/usage/email.rst
+++ b/docs/usage/email.rst
@@ -12,8 +12,17 @@ cannot be sent, all mails will show up i
 Before any email can be sent, an SMTP server has to be configured using the
 configuration file setting ``smtp_server``. If required for that server, specify
 a username (``smtp_username``) and password (``smtp_password``), a non-standard
-port (``smtp_port``), encryption settings (``smtp_use_tls`` or ``smtp_use_ssl``)
-and/or specific authentication parameters (``smtp_auth``).
+port (``smtp_port``), whether to use "SSL" when connecting (``smtp_use_ssl``)
+or use STARTTLS (``smtp_use_tls``), and/or specify special ESMTP "auth" features
+(``smtp_auth``).
+
+For example, for sending through gmail, use::
+
+    smtp_server = smtp.gmail.com
+    smtp_username = username
+    smtp_password = password
+    smtp_port = 465
+    smtp_use_ssl = true
 
 
 Application emails
diff --git a/kallithea/bin/template.ini.mako b/kallithea/bin/template.ini.mako
--- a/kallithea/bin/template.ini.mako
+++ b/kallithea/bin/template.ini.mako
@@ -49,17 +49,16 @@ pdebug = false
 #error_email_from = paste_error@example.com
 
 <%text>## SMTP server settings</%text>
-<%text>## Only smtp_server is mandatory. All other settings take the specified default</%text>
-<%text>## values.</%text>
+<%text>## If specifying credentials, make sure to use secure connections.</%text>
+<%text>## Default: Send unencrypted unauthenticated mails to the specified smtp_server.</%text>
+<%text>## For "SSL", use smtp_use_ssl = true and smtp_port = 465.</%text>
+<%text>## For "STARTTLS", use smtp_use_tls = true and smtp_port = 587.</%text>
 #smtp_server = smtp.example.com
 #smtp_username =
 #smtp_password =
 #smtp_port = 25
+#smtp_use_ssl = false
 #smtp_use_tls = false
-#smtp_use_ssl = false
-<%text>## SMTP authentication parameters to use (e.g. LOGIN PLAIN CRAM-MD5, etc.).</%text>
-<%text>## If empty, use any of the authentication parameters supported by the server.</%text>
-#smtp_auth =
 
 [server:main]
 %if http_server == 'paste':
diff --git a/kallithea/config/deployment.ini_tmpl b/kallithea/config/deployment.ini_tmpl
--- a/kallithea/config/deployment.ini_tmpl
+++ b/kallithea/config/deployment.ini_tmpl
@@ -50,17 +50,16 @@ pdebug = false
 #error_email_from = paste_error@example.com
 
 ## SMTP server settings
-## Only smtp_server is mandatory. All other settings take the specified default
-## values.
+## If specifying credentials, make sure to use secure connections.
+## Default: Send unencrypted unauthenticated mails to the specified smtp_server.
+## For "SSL", use smtp_use_ssl = true and smtp_port = 465.
+## For "STARTTLS", use smtp_use_tls = true and smtp_port = 587.
 #smtp_server = smtp.example.com
 #smtp_username =
 #smtp_password =
 #smtp_port = 25
+#smtp_use_ssl = false
 #smtp_use_tls = false
-#smtp_use_ssl = false
-## SMTP authentication parameters to use (e.g. LOGIN PLAIN CRAM-MD5, etc.).
-## If empty, use any of the authentication parameters supported by the server.
-#smtp_auth =
 
 [server:main]
 ## PASTE ##
diff --git a/kallithea/tests/test.ini b/kallithea/tests/test.ini
--- a/kallithea/tests/test.ini
+++ b/kallithea/tests/test.ini
@@ -53,17 +53,16 @@ pdebug = false
 #error_email_from = paste_error@example.com
 
 ## SMTP server settings
-## Only smtp_server is mandatory. All other settings take the specified default
-## values.
+## If specifying credentials, make sure to use secure connections.
+## Default: Send unencrypted unauthenticated mails to the specified smtp_server.
+## For "SSL", use smtp_use_ssl = true and smtp_port = 465.
+## For "STARTTLS", use smtp_use_tls = true and smtp_port = 587.
 #smtp_server = smtp.example.com
 #smtp_username =
 #smtp_password =
 #smtp_port = 25
+#smtp_use_ssl = false
 #smtp_use_tls = false
-#smtp_use_ssl = false
-## SMTP authentication parameters to use (e.g. LOGIN PLAIN CRAM-MD5, etc.).
-## If empty, use any of the authentication parameters supported by the server.
-#smtp_auth =
 
 [server:main]
 ## PASTE ##