summaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorTanguy Le Carrour <tanguy@bioneland.org>2023-05-17 10:51:44 +0200
committerLudovic Courtès <ludo@gnu.org>2023-05-30 00:15:30 +0200
commit110462bb2f1678fb0147a5845b2b48d0566ce0b4 (patch)
tree8f17b98ac4d00309f1a508a5d40850ae708e22ac /doc
parent4ebefac412147b8dcf076d57f624e72b8f583bc5 (diff)
home: services: Add msmtp service.
* gnu/home/services/mail.scm: New file. * gnu/local.mk (GNU_SYSTEM_MODULES): Add it. * doc/guix.texi (Mail Home Services): New node. Co-authored-by: Ludovic Courtès <ludo@gnu.org>
Diffstat (limited to 'doc')
-rw-r--r--doc/guix.texi137
1 files changed, 137 insertions, 0 deletions
diff --git a/doc/guix.texi b/doc/guix.texi
index 4314ec666c..47b2b8ba62 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -115,6 +115,7 @@ Copyright @copyright{} 2023 Giacomo Leidi@*
Copyright @copyright{} 2022 Antero Mejr@*
Copyright @copyright{} 2023 Karl Hallsby@*
Copyright @copyright{} 2023 Nathaniel Nicandro@*
+Copyright @copyright{} 2023 Tanguy Le Carrour@*
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
@@ -42292,6 +42293,7 @@ services)}.
* Guix: Guix Home Services. Services for Guix.
* Fonts: Fonts Home Services. Services for managing User's fonts.
* Sound: Sound Home Services. Dealing with audio.
+* Mail: Mail Home Services. Services for managing mail.
* Messaging: Messaging Home Services. Services for managing messaging.
* Media: Media Home Services. Services for managing media.
@end menu
@@ -43523,6 +43525,141 @@ Stopping the Shepherd service turns off broadcasting.
This is the multicast address used by default by the two services above.
@end defvar
+@node Mail Home Services
+@subsection Mail Home Services
+
+The @code{(gnu home services mail)} module provides services that help
+you set up the tools to work with emails in your home environment.
+
+@cindex msmtp
+@uref{https://marlam.de/msmtp, MSMTP} is a @acronym{SMTP, Simple Mail
+Transfer Protocol} client. It sends mail to a predefined SMTP server
+that takes care of proper delivery.
+
+The service reference is given below.
+
+@defvar home-msmtp-service-type
+This is the service type for @command{msmtp}. Its value must be a
+@code{home-msmtp-configuration}, as shown below. It provides the
+@file{~/.config/msmtp/config} file.
+
+As an example, here is how you would configure @code{msmtp} for a single
+account:
+
+@lisp
+(service home-msmtp-service-type
+ (home-msmtp-configuration
+ (accounts
+ (list
+ (msmtp-account
+ (name "alice")
+ (configuration
+ (msmtp-configuration
+ (host "mail.example.org")
+ (port 587)
+ (user "alice")
+ (password-eval "pass Mail/alice"))))))))
+@end lisp
+@end defvar
+
+@c %start of fragment
+
+@deftp {Data Type} home-msmtp-configuration
+Available @code{home-msmtp-configuration} fields are:
+
+@table @asis
+@item @code{defaults} (type: msmtp-configuration)
+The configuration that will be set as default for all accounts.
+
+@item @code{accounts} (default: @code{()}) (type: list-of-msmtp-accounts)
+A list of @code{msmtp-account} records which contain information about
+all your accounts.
+
+@item @code{default-account} (type: maybe-string)
+Set the default account.
+
+@item @code{extra-content} (default: @code{""}) (type: string)
+Extra content appended as-is to the configuration file. Run
+@command{man msmtp} for more information about the configuration file
+format.
+
+@end table
+
+@end deftp
+
+@c %end of fragment
+
+@c %start of fragment
+
+@deftp {Data Type} msmtp-account
+Available @code{msmtp-account} fields are:
+
+@table @asis
+@item @code{name} (type: string)
+The unique name of the account.
+
+@item @code{configuration} (type: msmtp-configuration)
+The configuration for this given account.
+
+@end table
+
+@end deftp
+
+@c %end of fragment
+
+@c %start of fragment
+
+@deftp {Data Type} msmtp-configuration
+Available @code{msmtp-configuration} fields are:
+
+@table @asis
+@item @code{auth?} (type: maybe-boolean)
+Enable or disable authentication.
+
+@item @code{tls?} (type: maybe-boolean)
+Enable or disable TLS (also known as SSL) for secured connections.
+
+@item @code{tls-starttls?} (type: maybe-boolean)
+Choose the TLS variant: start TLS from within the session (‘on’,
+default), or tunnel the session through TLS (‘off’).
+
+@item @code{tls-trust-file} (type: maybe-string)
+Activate server certificate verification using a list of trusted
+Certification Authorities (CAs).
+
+@item @code{log-file} (type: maybe-string)
+Enable logging to the specified file. An empty argument disables
+logging. The file name ‘-’ directs the log information to standard
+output.
+
+@item @code{host} (type: maybe-string)
+The SMTP server to send the mail to.
+
+@item @code{port} (type: maybe-integer)
+The port that the SMTP server listens on. The default is 25 ("smtp"),
+unless TLS without STARTTLS is used, in which case it is 465 ("smtps").
+
+@item @code{user} (type: maybe-string)
+Set the user name for authentication.
+
+@item @code{from} (type: maybe-string)
+Set the envelope-from address.
+
+@item @code{password-eval} (type: maybe-string)
+Set the password for authentication to the output (stdout) of the
+command cmd.
+
+@item @code{extra-content} (default: @code{""}) (type: string)
+Extra content appended as-is to the configuration block. Run
+@command{man msmtp} for more information about the configuration file
+format.
+
+@end table
+
+@end deftp
+
+@c %end of fragment
+
@node Messaging Home Services
@subsection Messaging Home Services