### Example: Managing msmtpd with start-stop-daemon

Source: https://marlam.de/msmtp/msmtp

Shell commands demonstrating how to start and stop the msmtpd service using the start-stop-daemon utility, including PID file management and user switching.

```shell
# start msmtpd
start-stop-daemon --start --pidfile /var/run/msmtpd.pid --make-pidfile --chuid msmtpd --background --exec /usr/local/bin/msmtpd -- --command '/usr/local/bin/msmtp -f %F --'
# stop msmtpd
start-stop-daemon --stop  --pidfile /var/run/msmtpd.pid --remove-pidfile --quiet --signal TERM
```

--------------------------------

### msmtp User Configuration File Example

Source: https://marlam.de/msmtp/msmtp

An example of a user configuration file (~/.msmtprc) for msmtp, demonstrating settings for TLS, port, and account configuration for a freemail service.

```ini
# Example for a user configuration file ~/.msmtprc
#
# This file focusses on TLS and authentication. Features not used here include
# logging, timeouts, SOCKS proxies, TLS parameters, Delivery Status Notification
# (DSN) settings, and more.

# Set default values for all following accounts.
defaults

# Use the mail submission port 587 instead of the SMTP port 25.
port 587

# Always use TLS.
tls on

# Set a list of trusted CAs for TLS. The default is to use system settings, but
# you can select your own file.
#tls_trust_file /etc/ssl/certs/ca-certificates.crt

# A freemail service
account freemail

# Host name of the SMTP server
host smtp.freemail.example
```

--------------------------------

### msmtp General Setup Commands

Source: https://marlam.de/msmtp/msmtp

Defines default settings and account configurations for msmtp. The 'defaults' command sets global defaults, while 'account' defines specific mail accounts, optionally inheriting settings from other accounts.

```APIDOC
defaults
  Sets default values for all following account definitions.

account name [: account[,…]]
  Starts a new account definition. Fills in current default values. If a list of previously defined accounts is given after the account name, the new account inherits settings from those accounts.
  Parameters:
    name: The name of the new account.
    account[,…]: Optional list of existing accounts to inherit settings from.
```

--------------------------------

### msmtp System-Wide Configuration

Source: https://marlam.de/msmtp/msmtp

An example of a system-wide msmtp configuration file, typically used to define a default account and enable msmtp to function like a system sendmail binary.

```msmtp-config
# A system wide configuration file is optional.
# If it exists, it usually defines a default account.
# This allows msmtp to be used like /usr/sbin/sendmail.
account default

# The SMTP smarthost
host mail.oursite.example

# Use TLS on port 465
port 465
tls on
tls_starttls off

# Construct envelope-from addresses of the form "user@oursite.example"
from %U@oursite.example

# Syslog logging with facility LOG_MAIL instead of the default LOG_USER
syslog LOG_MAIL
```

--------------------------------

### msmtp Configuration File Structure

Source: https://marlam.de/msmtp/msmtp

Describes the general syntax and rules for msmtp configuration files. Empty lines and lines starting with '#' are ignored. Other lines contain commands and optional arguments, which can be enclosed in double quotes. Tilde (~) is expanded to the HOME directory.

```APIDOC
Configuration File Syntax:

- Empty lines and comment lines (starting with '#') are ignored.
- Each non-empty, non-comment line must contain a command and an optional argument.
- Arguments can be enclosed in double quotes (").
- A leading tilde (~) in a file name is replaced by the user's HOME directory.
- Commands are organized into accounts, each starting with the 'account' command.
- If a command accepts 'on', an empty argument is treated as 'on'.
```

--------------------------------

### msmtp Aliases File Example

Source: https://marlam.de/msmtp/msmtp

An example of an aliases file used to redirect mail for specific recipients to different email addresses. This allows for flexible mail routing.

```aliases
# Example aliases file

# Send root to Joe and Jane
root: joe_smith@example.com, jane_chang@example.com

# Send cron to Mark
cron: mark_jones@example.com

# Send everything else to admin
default: admin@domain.example
```

--------------------------------

### msmtp Operation Mode Options

Source: https://marlam.de/msmtp/msmtp

Options to change the program's operational mode. `--configure` generates a mail address configuration. `--serverinfo` retrieves and displays SMTP server details and supported features. `--rmqs` initiates a Remote Message Queue Starting request to the SMTP server.

```APIDOC
--configure=mailaddress
  Generate a configuration for the given mail address and print it. This can be modified or copied unchanged to the configuration file. Note that this only works for mail domains that publish appropriate SRV records; see RFC 8314.
```

```APIDOC
--serverinfo
  Print information about the SMTP server and exit. This includes information about supported features (mail size limit, authentication, TLS, DSN, ...) and about the TLS certificate (if TLS is active). See [Server information mode].
```

```APIDOC
--rmqs=(host|@domain|#queue)
  Send a Remote Message Queue Starting request for the given host, domain, or queue to the SMTP server and exit. See [Remote Message Queue Starting mode].
```

--------------------------------

### msmtp Password Evaluation for PKCS#11 PIN

Source: https://marlam.de/msmtp/msmtp

Specifies a command to evaluate the password (PIN) required to access PKCS#11 devices. This example uses `gpg2` to securely decrypt a PIN stored in a file.

```APIDOC
passwordeval gpg2 --no-tty -q -d ~/.smart-card-pin.gpg
```

--------------------------------

### msmtp Remote Message Queue Starting (RMQS) Destinations

Source: https://marlam.de/msmtp/msmtp

Specifies the destinations for Remote Message Queue Starting requests using the ETRN SMTP command. This allows a client to request a server to process its mail queues for specific hosts, domains, or queues.

```APIDOC
--rmqs <destination>
  - Sends a request for the server to start processing mail queues.

Destinations:
  host
    - Request messages for the given host.
  @domain
    - Request messages for the given domain.
  #queue
    - Request delivery of messages in the given queue.
```

--------------------------------

### msmtp General Command-Line Options

Source: https://marlam.de/msmtp/msmtp

Provides essential options for version checking, help display, dry runs, and debugging. `--version` shows program and library details. `--help` displays usage information. `--pretend` simulates actions without execution, masking sensitive data. `--debug` outputs verbose server communication, including potentially sensitive information.

```APIDOC
--version
  Print version information, including information about the libraries used.
```

```APIDOC
--help
  Print help.
```

```APIDOC
--pretend, -P
  Print the configuration settings that would be used, but do not take further action. An asterisk ('*') will be printed instead of the password.
```

```APIDOC
--debug, -v, -d
  Print lots of debugging information, including the whole conversation with the server. Be careful with this option: the (potentially dangerous) output will not be sanitized, and your password may get printed in an easily decodable format!
```

--------------------------------

### msmtpd Command-line Options

Source: https://marlam.de/msmtp/msmtp

Lists and describes the available command-line options for configuring and running the msmtpd server, including interface, port, logging, command piping, and authentication settings.

```APIDOC
--version
  Print version information

--help
  Print help.

--inetd
  Start single SMTP session on stdin/stdout

--interface=ip
  Listen on the given IPv6 or IPv4 address instead of 127.0.0.1

--port=number
  Listen on the given port number instead of 25

--log=none|syslog|filename
  Set logging: none (default), syslog, or logging to the given file.

--command=cmd
  Pipe mails to cmd instead of msmtp.
  Make sure to end this command with `--` to separate options from arguments.

--auth=user[,passwordeval]
  Require authentication with this user name. The password will be retrieved from the given passwordeval command (this works just like passwordeval in msmtp) or, if none is given, from the key ring or, if that fails, from a prompt.
```

--------------------------------

### msmtp Command Line Options

Source: https://marlam.de/msmtp/msmtp

Details common command-line options for msmtp, such as `--configure` for generating configuration suggestions and `--version` for displaying the system-dependent directory for system-wide configuration.

```APIDOC
Command Line Options:

--configure
  Generates a suggestion for a suitable configuration file.

--version
  Prints the version and the system-dependent directory (SYSCONFDIR) where msmtp looks for its system-wide configuration file.
```

--------------------------------

### msmtp Command Synopsis and Options

Source: https://marlam.de/msmtp/msmtp

Provides the command-line synopsis for msmtp and details its various options, including general settings, mode changes, configuration directives, and sendmail-specific options.

```APIDOC
msmtp [OPTIONS] [ADDRESSES]

Synopsis:
  msmtp reads a mail from standard input and sends it to a predefined SMTP server.

Options:
  --help                Display help message and exit.
  --version             Print version information and exit.
  -a, --account=NAME    Use account NAME.
  -A, --add-header=NAME=VALUE
                        Add a header line.
  -B, --read-recipients=FILE
                        Read recipients from FILE.
  -c, --configcheck     Check configuration files and exit.
  -d, --debug[=LEVEL]   Enable debugging.
  -e, --echo            Echo mail to stdout.
  -f, --force-from=ADDRESS
                        Force From: address.
  -F, --force-from-name=NAME
                        Force From: name.
  -h, --help            Display help message and exit.
  -i, --read-envelope-from=FILE
                        Read envelope sender from FILE.
  -m, --mail-from=ADDRESS
                        Set envelope sender address.
  -N, --no-file-from    Do not use From: address from configuration file.
  -o, --options=FILE    Read options from FILE.
  -p, --print-config    Print configuration and exit.
  -P, --print-password  Print password and exit.
  -q, --queue=DIR       Use mail queue in DIR.
  -r, --read-recipients=FILE
                        Read recipients from FILE.
  -R, --read-envelope-from=FILE
                        Read envelope sender from FILE.
  -s, --sendmail-mode   Enable sendmail compatibility mode.
  -S, --server-info-mode
                        Enable server information mode.
  -t, --read-recipients-from-header
                        Read recipients from To:, Cc:, Bcc: headers.
  -u, --user=USER       Use USER for authentication.
  -v, --verbose         Enable verbose output.
  -V, --version         Print version information and exit.
  -x, --rmqs-mode       Enable Remote Message Queue Starting mode.

Configuration Options (in configuration files):
  account NAME
    host <hostname>
    port <port>
    from <address>
    tls <on|off|yes|no>
    tls_starttls <on|off|yes|no>
    tls_trust_certificates <file>
    tls_verify <on|off|yes|no>
    tls_fingerprint <fingerprint>
    tls_ciphers <cipher_list>
    auth <method>
    user <username>
    password <password>
    passwordeval <command>
    
  Other options:
    logfile <file>
    logfile_append <on|off>
    syslog <facility>
    
  Sendmail mode specific options:
    sendmail_path <path>
    
  Server information mode specific options:
    server_info_host <hostname>
    server_info_port <port>
    
  Remote Message Queue Starting mode specific options:
    rmqs_host <hostname>
    rmqs_port <port>
    rmqs_command <command>

Related Commands:
  msmtpd (Minimal SMTP server)
```

--------------------------------

### msmtp Configuration: Password Methods

Source: https://marlam.de/msmtp/msmtp

Demonstrates various methods for handling passwords in msmtp configuration files. Options include using system keyrings, encrypted files with password evaluation, direct cleartext passwords, and prompting the user.

```msmtp-config
# Password method 1: Add the password to the system keyring, and let msmtp get
# it automatically. To set the keyring password using Gnome's libsecret:
# $ secret-tool store --label=msmtp \
#   host smtp.freemail.example \
#   service smtp \
#   user joe.smith

# Password method 2: Store the password in an encrypted file, and tell msmtp
# which command to use to decrypt it. This is usually used with GnuPG, as in
# this example. Usually gpg-agent will ask once for the decryption password.
passwordeval gpg2 --no-tty -q -d ~/.msmtp-password.gpg

# Password method 3: Store the password directly in this file. Usually it is not
# a good idea to store passwords in cleartext files. If you do it anyway, at
# least make sure that this file can only be read by yourself.
#password secret123

# Password method 4: Store the password in ~/.netrc. This method is probably not
# relevant anymore.

# Password method 5: Do not specify a password. Msmtp will then prompt you for
# it. This means you need to be able to type into a terminal when msmtp runs.
```

--------------------------------

### Authentication Commands

Source: https://marlam.de/msmtp/msmtp

Details commands for configuring authentication methods, user credentials, and NTLM domains. Includes enabling/disabling authentication, setting usernames and passwords, using command-line evaluation for passwords, and specifying NTLM domains.

```APIDOC
auth [(on|off|method)]
- Enable or disable authentication and optionally choose a method to use. The argument ‘on’ chooses a method automatically.
- Accepted methods: scram-sha-256-plus, scram-sha-1-plus, scram-sha-256, scram-sha-1, plain, gssapi, external, oauthbearer, cram-md5, digest-md5, login, ntlm, xoauth2.
- See [Authentication](#Authentication).
```

```APIDOC
user [username]
- Set the user name for authentication. An empty argument unsets the user name.
- Authentication must be activated with the ‘auth’ command.
```

```APIDOC
password [secret]
- Set the password for authentication. An empty argument unsets the password.
- Consider using the ‘passwordeval’ command or a key ring instead of this command, to avoid storing cleartext passwords in the configuration file.
- See [Authentication](#Authentication).
```

```APIDOC
passwordeval [cmd]
- Set the password for authentication to the output (stdout) of the command cmd.
- This can be used e.g. to decrypt password files on the fly or to query key rings, and thus to avoid storing cleartext passwords.
- The cmd command must not mess with standard input; if in doubt, append < /dev/null.
- See [Authentication](#Authentication).
```

```APIDOC
ntlmdomain [ntlmdomain]
- Set a domain for the ‘ntlm’ authentication method. This is obsolete.
```

--------------------------------

### msmtp Invocation Modes

Source: https://marlam.de/msmtp/msmtp

Describes the different ways msmtp can be invoked, including sendmail compatibility, configuration, server info, and message queue operations.

```APIDOC
Invocation Synopsis:

Sendmail mode (default):
  msmtp [option…] [--] recipient…
  msmtp [option…] -t [--] [recipient…]

Configuration mode:
  msmtp --configure mailaddress

Server information mode:
  msmtp [option…] --serverinfo

Remote Message Queue Starting mode:
  msmtp [option…] --rmqs=(host|@domain|#queue)

Options override configuration file settings and are compatible with sendmail where appropriate.

Invocation Categories:
- General options
- Changing the mode of operation
- Configuration options
- Options specific to sendmail mode
```

--------------------------------

### msmtp Account and Command Structure

Source: https://marlam.de/msmtp/msmtp

Defines how accounts and commands are structured within an msmtp configuration file. Each account begins with the 'account' command, followed by settings specific to that account. Commands are organized into categories such as General, Authentication, and TLS.

```APIDOC
Account and Command Structure:

- Accounts are defined using the 'account' command.
- Each account block contains settings for a single SMTP account.
- Commands are organized into categories:
  - General commands
  - Authentication commands
  - TLS commands
  - Commands specific to sendmail mode
```

--------------------------------

### msmtp Command-Line Configuration Options

Source: https://marlam.de/msmtp/msmtp

This section details the various command-line options available for configuring the msmtp mail client. These options allow users to specify configuration files, accounts, network settings, authentication methods, and TLS/SSL parameters directly from the command line, overriding or supplementing settings found in configuration files.

```APIDOC
msmtp Command-Line Options:

Configuration File:
  -C filename
  --file=filename
    Use the given file instead of default locations (~/.msmtprc or XDG_CONFIG_HOME/msmtp/config) as the user configuration file.
    Parameters:
      filename: Path to the msmtp configuration file.

Account Selection:
  -a account
  --account=account
    Use the given account instead of the account named 'default'. This option cannot be used together with the --host option.
    Parameters:
      account: The name of the account to use.

Host and Network Settings:
  --host=hostname
    Use this server with settings from the command line; do not use any configuration file data. This option cannot be used together with the --account option. It disables loading of configuration files.
    Parameters:
      hostname: The hostname of the mail server.

  --port=number
    Set the port number to connect to.
    Parameters:
      number: The port number (e.g., 587).

  --source-ip=[IP]
    Set or unset an IP address to bind the socket to.
    Parameters:
      IP: The IP address to bind the socket to.

  --proxy-host=[IP|hostname]
    Set or unset a SOCKS proxy to use.
    Parameters:
      IP|hostname: The hostname or IP address of the SOCKS proxy.

  --proxy-port=[number]
    Set or unset a port number for the proxy host.
    Parameters:
      number: The port number for the proxy host.

  --socket=[socketname]
    Set or unset a local unix domain socket name to connect to.
    Parameters:
      socketname: The name of the unix domain socket.

  --timeout=(off|seconds)
    Set or unset a network timeout, in seconds.
    Parameters:
      off|seconds: 'off' to disable timeout, or a number of seconds.

Protocol and Domain:
  --protocol=(smtp|lmtp)
    Set the protocol to use (SMTP or LMTP).
    Parameters:
      smtp|lmtp: The protocol to use.

  --domain=[argument]
    Set the argument of the SMTP EHLO (or LMTP LHLO) command, and the domain part for the Message-ID header.
    Parameters:
      argument: The domain argument.

Authentication:
  --auth[=(on|off|method)]
    Enable or disable authentication and optionally choose the method.
    Parameters:
      on|off|method: 'on' to enable default authentication, 'off' to disable, or specify an authentication method (e.g., 'plain', 'login').

  --user=[username]
    Set or unset the user name for authentication.
    Parameters:
      username: The username for authentication.

  --passwordeval=[eval]
    Evaluate password for authentication. This allows for dynamic password retrieval.
    Parameters:
      eval: An expression or command to evaluate for the password.

TLS/SSL Settings:
  --tls[=(on|off)]
    Enable or disable TLS/SSL encryption.
    Parameters:
      on|off: 'on' to enable TLS/SSL, 'off' to disable.

  --tls-starttls[=(on|off)]
    Enable or disable STARTTLS for TLS encryption.
    Parameters:
      on|off: 'on' to enable STARTTLS, 'off' to disable.

  --tls-trust-file=[file]
    Set or unset a trust file for TLS certificate verification.
    Parameters:
      file: Path to the trust file (e.g., CA bundle).

  --tls-crl-file=[file]
    Deprecated. Set or unset a certificate revocation list (CRL) file for TLS.
    Parameters:
      file: Path to the CRL file.

  --tls-fingerprint=[fingerprint]
    Set or unset the fingerprint of a trusted TLS certificate.
    Parameters:
      fingerprint: The certificate fingerprint.

  --tls-key-file=[file]
    Set or unset a key file for TLS client authentication.
    Parameters:
      file: Path to the private key file.

  --tls-cert-file=[file]
    Set or unset a certificate file for TLS client authentication.
    Parameters:
      file: Path to the certificate file.

  --tls-certcheck[=(on|off)]
    Enable or disable server certificate checks for TLS.
    Parameters:
      on|off: 'on' to enable checks, 'off' to disable.

  --tls-priorities=[priorities]
    Set or unset TLS cipher suite priorities.
    Parameters:
      priorities: A string specifying the TLS cipher suite order.

  --tls-host-override=[host]
    Set or unset override for TLS host verification. Useful when the certificate's hostname differs from the server's hostname.
    Parameters:
      host: The hostname to use for verification.

  --tls-min-dh-prime-bits=[bits]
    Deprecated, use '--tls-priorities' instead. Set or unset minimum bit size of the Diffie-Hellman (DH) prime.
    Parameters:
      bits: The minimum bit size for DH prime.

```

--------------------------------

### msmtp: Account Selection Logic

Source: https://marlam.de/msmtp/msmtp

Explains the three methods msmtp uses to select an email account: explicitly via `--account`, by host settings via `--host`, or by matching the envelope-from address. Default account is 'default' if no match is found.

```APIDOC
msmtp Account Selection Logic:

1. --account=account: Use the specified account. Command line settings override configuration file settings.
2. --host=hostname: Use only command line settings; ignore configuration file data.
3. --from=address or --read-envelope-from: Choose the first account from configuration files that matches the envelope-from address specified by a 'from' command. Subaddresses and wildcard patterns in the 'from' address are supported.

If none of these options are used, or if no account matches, the 'default' account is used.
```

--------------------------------

### Complete msmtpd Command for SMTP Proxy

Source: https://marlam.de/msmtp/msmtp

Provides the full command to launch msmtpd as an SMTP server, listening on a specific port and using a configured user for authentication. It specifies the backend msmtp command for sending mail.

```shell
msmtpd --port=2500 --auth=msmtpd-user --command='/path/to/your/msmtp -f %F --'
```

--------------------------------

### msmtp Envelope From Address Configuration

Source: https://marlam.de/msmtp/msmtp

Configures the envelope-from address and related overrides for msmtp. Includes setting the primary envelope-from address with supported substitution patterns, defining a full name for the From header, and controlling whether the `--from` option can override the configured envelope-from address.

```APIDOC
from [address]
  Set the envelope-from address. The following substitution patterns are supported:
  * %F: Address from the From header.
  * %U: Username (USER, LOGNAME, or login name).
  * %H: Hostname.
  * %C: Canonical name of %H.
  * %M: Contents of /etc/mailname.
  The envelope-from address can also be a wildcard pattern.
```

```APIDOC
from_full_name name
  Set a full name to be used in a From header if msmtp adds one. See [set_from_header](#set_005ffrom_005fheader).
```

```APIDOC
allow_from_override (on|off)
  By default, the [--from](#g_t_002d_002dfrom) option overrides the [from](#from) command. Set to 'off' to disable this.
```

--------------------------------

### msmtp Proxy Configuration

Source: https://marlam.de/msmtp/msmtp

Enables and configures the use of a SOCKS proxy for all network traffic, including DNS queries.

```APIDOC
proxy_host [IP|hostname]
  Specifies the SOCKS proxy host. All network traffic will be routed through this proxy. An empty argument disables proxy usage.
  Parameters:
    IP|hostname: The hostname or IP address of the SOCKS proxy.

proxy_port [number]
  Sets the port number for the proxy host. An empty 'number' argument resets the proxy port to the default, which is 1080 ('socks').
  Parameters:
    number: The port number for the proxy.
```

--------------------------------

### msmtp TLS Configuration

Source: https://marlam.de/msmtp/msmtp

Configuration commands for managing TLS/SSL settings in msmtp, including enabling/disabling, certificate validation, and key management.

```APIDOC
TLS Commands:

'tls [(on|off)]'
  Enable or disable TLS (also known as SSL) for secured connections.

'tls_starttls [(on|off)]'
  Choose the TLS variant: start TLS from within the session ('on', default), or tunnel the session through TLS ('off').

'tls_trust_file [file]'
  Activate server certificate verification using a list of trusted Certification Authorities (CAs). The default is 'system'. An empty argument disables trust in CAs. The file must be in PEM format.

'tls_crl_file [file]'
  Sets a certificate revocation list (CRL) file for TLS to check for revoked certificates. An empty argument disables this. OCSP is an alternative.

'tls_fingerprint [fingerprint]'
  Set the fingerprint of a single certificate to accept for TLS. This certificate will be trusted regardless of its contents, overriding 'tls_trust_file'. The fingerprint should be SHA256, but SHA1 or MD5 are supported for backward compatibility. Format: '01:23:45:67:…'.

'tls_key_file [file]'
  Send a client certificate to the server, used with 'tls_cert_file'. The file must contain the private key of a certificate in PEM format. An empty argument disables this feature.

'tls_cert_file [file]'
  Send a client certificate to the server, used with 'tls_key_file'. The file must contain a certificate in PEM format. An empty argument disables this feature.

'tls_certcheck [(on|off)]'
  Enable or disable checks of the server certificate. They are enabled by default and override 'tls_trust_file' and 'tls_fingerprint'. Disabling them makes TLS sessions insecure.

'tls_priorities [priorities]'
  Set priorities for TLS session parameters. The interpretation depends on the TLS library (GnuTLS or libtls). For libtls, format is 'PROTOCOLS=... CIPHERS=... ECDHECURVES=...'. Example: 'PROTOCOLS=TLSv1.3 CIPHERS=ECDHE-RSA-AES128-SHA256 ECDHECURVES=P-384'.

'tls_host_override [host]'
  Allows using a different host name for TLS host verification than the one specified by the 'host' command. Useful in special cases.

'tls_min_dh_prime_bits [bits]'
  Deprecated, use 'tls_priorities' instead. Set or unset the minimum number of Diffie-Hellman (DH) prime bits accepted for TLS sessions. Lowering the default (e.g., to 512 bits) should only be done if TLS fails with the remote server.
```

--------------------------------

### msmtp: Logging Options

Source: https://marlam.de/msmtp/msmtp

Configures logging behavior for msmtp. Options include setting a log file path, defining the time format for log entries, and enabling/disabling syslog logging.

```APIDOC
msmtp Options: Logging

-X [file]
--logfile=[file]
  Set or unset the log file. See [logfile](#logfile).

--logfile-time-format=[fmt]
  Set or unset the log file time format. See [logfile_time_format](#logfile_005ftime_005fformat).

--syslog[=(on|off|facility)]
  Enable or disable syslog logging. See [syslog](#syslog).
```

--------------------------------

### msmtp Execution and Evaluation

Source: https://marlam.de/msmtp/msmtp

Controls how configuration lines are processed, allowing for dynamic content generation or decryption. The 'eval' command replaces a configuration line with the output of an external command.

```APIDOC
eval [cmd]
  Replaces the current configuration file line with the first line of the output (stdout) of the command 'cmd'. Useful for decrypting settings or generating them via scripts.
  Note: Every 'eval' line is evaluated when the configuration file is read. The command must not interfere with standard input; append '< /dev/null' if in doubt.
  Example: `eval echo host localhost` replaces the current line with `host localhost`.
  Related: 'passwordeval' for password-specific evaluation.
```

--------------------------------

### msmtp Configuration File Loading

Source: https://marlam.de/msmtp/msmtp

Explains the hierarchy and precedence of msmtp configuration files. A system-wide configuration file (`SYSCONFDIR/msmtprc`) is loaded if it exists and is readable. User configuration files (`~/.msmtprc` or `$XDG_CONFIG_HOME/msmtp/config`) override settings from the system file. Command-line options can further modify settings.

```APIDOC
Configuration File Loading Order:

1. System-wide configuration file: `SYSCONFDIR/msmtprc` (loaded if readable).
2. User configuration file: `~/.msmtprc` or `$XDG_CONFIG_HOME/msmtp/config` (overrides system file settings).
3. Command-line options: Can override settings from both configuration files.
```

--------------------------------

### msmtp Logging Configuration and Format

Source: https://marlam.de/msmtp/msmtp

Configures logging for msmtp, detailing the information captured for each mail sending attempt. Supports logging to a file with time formatting or to syslog.

```APIDOC
logfile:
  Description: Specifies the path to the log file.
  Example: logfile /var/log/msmtp.log
```

```APIDOC
logfile_time_format:
  Description: Defines the time format prepended to log file entries.
  Format: strftime(3) compatible string.
  Example: logfile_time_format %Y-%m-%d %H:%M:%S
```

```APIDOC
syslog:
  Description: Enables logging to the syslog service.
  Parameters:
    facility: The syslog facility to use (e.g., mail, user).
  Example: syslog mail
```

```APIDOC
Log Line Format:
  Description: Structure of a single log line generated by msmtp.
  Fields:
    host=hostname: Host name of the SMTP server.
    tls=(on|off): Indicates if TLS was used.
    auth=(on|off): Indicates if authentication was used.
    user=name: User name for authentication (if auth is on).
    from=address: The envelope-from address.
    recipients=addr1,addr2,…: The recipient addresses.
    mailsize=number: Size of the mail in bytes (on success).
    smtpstatus=number: SMTP status code (on failure).
    smtpmsg='message': SMTP error message (on failure).
    errormsg='message': msmtp error message (on failure).
    exitcode=EX_…: msmtp exit code (e.g., EX_OK for success).
```

--------------------------------

### Mutt Configuration: Switching msmtp Accounts

Source: https://marlam.de/msmtp/msmtp

Provides Mutt configuration macros to easily switch between different msmtp accounts while composing an email. Users can press key combinations to change the sender address and associated msmtp account.

```mutt-config
# Switch accounts using <esc>1, <esc>2, <esc>3
macro generic "<esc>1" ":set from=you@example.com"
macro generic "<esc>2" ":set from=you@your-employer.example"
macro generic "<esc>3" ":set from=you@some-other-provider.example"

# Example for switching accounts with <tab> and seeing the current account with =
# Ensure the path to msmtp is correct
# macro compose \Cx_ ":set sendmail"
# macro compose \Cx| "\Cx_ = \"/usr/local/bin/msmtp"
# macro compose \Cx& ":macro compose \t \Cx"
# macro compose <tab> "\Cx0"
# macro compose = "\Cx_\n"
# Add account definitions below, e.g.:
# # Don't forget to put the number of the account at the beginning
# # account 1: you@example.com
# # account 2: you@your-employer.example
```

--------------------------------

### msmtp Configuration: Multiple Accounts

Source: https://marlam.de/msmtp/msmtp

Shows how to define multiple email accounts within a single msmtp configuration file, allowing users to manage different email services or identities.

```msmtp-config
# A second mail address at the same freemail service
account freemail2 : freemail
from joey@freemail.example

# The SMTP server of your ISP
account isp
host mail.isp.example
from smithjoe@isp.example
auth on
user 12345

# Set a default account
account default : freemail
```

--------------------------------

### msmtp Macros Configuration

Source: https://marlam.de/msmtp/msmtp

Defines macros for switching between different msmtp accounts or configurations. These macros are likely used within a text editor or mail client context.

```msmtp-config
macro compose \Cx0 "\Cx|\"\n\Cx&1\n\Cx_\n" # default and switch to 1
macro compose \Cx1 "\Cx| -a example_account\"\n\Cx&2\n\Cx_\n" # switch to 2
macro compose \Cx2 "\Cx| -a gmail\"\n\Cx&0\n\Cx_\n" # switch to 0
```

--------------------------------

### msmtp Network and Domain Settings

Source: https://marlam.de/msmtp/msmtp

Configures advanced network options like source IP binding, timeouts, and the domain used in SMTP/LMTP commands and message IDs.

```APIDOC
source_ip [IP]
  Binds the outgoing connection to a specific source IP address. Useful on multi-home systems. An empty argument disables this feature.
  Parameters:
    IP: The source IP address to bind to.

socket [socketname]
  Specifies a Unix domain socket to connect to, overriding 'host'/'port' and 'proxy_host'/'proxy_port' settings.
  Parameters:
    socketname: The file path for the Unix domain socket.

timeout (off|seconds)
  Sets or unsets a network timeout in seconds. 'off' uses the operating system's default timeout.
  Parameters:
    off: Disables the msmtp-specific timeout.
    seconds: The timeout duration in seconds.

domain argument
  Sets the argument for the SMTP EHLO (or LMTP LHLO) command and the domain part of Message-ID headers. Supports substitution patterns like %H (hostname), %C (canonical hostname), and %M (/etc/mailname).
  Parameters:
    argument: The domain string. Can be a domain name or use substitution patterns.
```

--------------------------------

### Mutt Configuration: Specifying msmtp Account

Source: https://marlam.de/msmtp/msmtp

Shows how to configure Mutt to explicitly specify which msmtp account to use, either by passing the account name via the sendmail command or by using the `-f` option with the sender's address.

```mutt-config
# Use a specific msmtp account
set sendmail="/path/to/msmtp -a my_account"

# Alternatively, let Mutt use the -f option to choose an account based on the from address
# set envelope_from=yes

# Or set everything from the command line:
# set sendmail="/path/to/msmtp --host=mailhub -f me@example.com --tls"
```

--------------------------------

### Configure msmtp for TLS Client Certificates

Source: https://marlam.de/msmtp/msmtp

Enables Transport Layer Security (TLS) for msmtp and specifies the client certificate and key files for authentication. Requires the `tls` option to be set to `on`.

```config
# Enable TLS
tls on
# Enable TLS client certificates
tls_cert_file /path/to/client_cert
tls_key_file /path/to/client_key
```

--------------------------------

### Mutt Configuration: Basic msmtp Integration

Source: https://marlam.de/msmtp/msmtp

Configures the Mutt email client to use msmtp as its sendmail program. It sets essential options like the sendmail path, enabling the use of the 'from' address, and setting the real name and default sender address.

```mutt-config
set sendmail="/path/to/msmtp"
set use_from=yes
set realname="Your Name"
set from=you@example.com
set envelope_from=yes
```

--------------------------------

### Store Password with secret-tool

Source: https://marlam.de/msmtp/msmtp

Demonstrates how to securely store a password for the msmtpd user using the secret-tool command, typically for keyring integration. This method allows msmtpd to retrieve the password without exposing it directly.

```shell
secret-tool store --label=msmtpd host localhost service smtp user msmtpd-user
```

--------------------------------

### msmtp Connection Settings

Source: https://marlam.de/msmtp/msmtp

Configures the primary connection details for sending mail, including the target SMTP server, port, and protocol.

```APIDOC
host hostname
  Specifies the SMTP server to send mail to. The argument can be a hostname or a network address. This command is mandatory for every account definition.
  Parameters:
    hostname: The hostname or IP address of the SMTP server.

port number
  Sets the port number the SMTP server listens on. Defaults to 25 ('smtp'). If TLS without STARTTLS is used, the default is 465 ('smtps').
  Parameters:
    number: The port number.

protocol (smtp|lmtp)
  Sets the protocol to use for sending mail. Currently supports 'smtp' (default) and 'lmtp'. See 'port' for default ports associated with each protocol.
  Parameters:
    smtp: Simple Mail Transfer Protocol.
    lmtp: Local Mail Transfer Protocol.
```

--------------------------------

### msmtp PKCS#11 TLS Certificate and Key Configuration

Source: https://marlam.de/msmtp/msmtp

Configures msmtp to use client certificates and private keys stored on external authentication devices via PKCS#11. This requires GnuTLS and the `p11tool` utility to find correct URIs.

```APIDOC
tls_cert_file pkcs11:model=PKCS%2315%20emulated;manufacturer=piv_II;serial=00000000;token=PIV_II%20%28PIV%20Card%20Holder%20pin%29;id=%01;object=Certificate%20for%20PIV%20Authentication;type=cert
tls_key_file  pkcs11:model=PKCS%2315%20emulated;manufacturer=piv_II;serial=00000000;token=PIV_II%20%28PIV%20Card%20Holder%20pin%29;id=%01;object=PIV%20AUTH%20key;type=private
```

--------------------------------

### msmtp Configuration Options

Source: https://marlam.de/msmtp/msmtp

Configuration commands that modify msmtp's default behavior for handling email headers. These options control the addition or removal of specific headers like Bcc, From, Date, Message-ID, and To.

```APIDOC
remove_bcc_headers
  - Controls the removal of Bcc header(s) from emails.

set_from_header
  - Controls the addition of a From header if the mail does not have one. Uses the envelope from address and optionally a full name.

set_date_header
  - Controls the addition of a Date header if the mail does not have one.

set_msgid_header
  - Controls the addition of a Message-ID header if the mail does not have one.

set_to_header
  - When set, replaces original To, Cc, and Bcc headers with a new To header.
```

--------------------------------

### msmtp Configuration Directives

Source: https://marlam.de/msmtp/msmtp

Configuration commands to control msmtp's behavior regarding email headers, logging, recipient handling, and envelope addresses.

```APIDOC
set_to_header [(on|off|undisclosed_recipients)]
  - Controls the handling of To, Cc, and Bcc headers. When 'on' or 'undisclosed_recipients', original headers are removed and a new To header is added. 'on' includes all recipients, while 'undisclosed_recipients' sets the header to 'To: undisclosed-recipients:;'. Default is 'off'.
  - For compatibility, 'undisclosed_recipients [(on|off)]' is also supported.

remove_bcc_headers [(on|off)]
  - Determines whether Bcc headers are removed. Default is to remove them.

logfile [file]
  - Enables logging to the specified file. An empty argument disables logging. '-' directs logs to standard output.

logfile_time_format [fmt]
  - Sets or unsets the log file time format using strftime() format string. An empty argument uses the default ('%b %d %H:%M:%S'). 'none' suppresses time output.

syslog [(on|off|facility)]
  - Enables or disables syslog logging. 'facility' can be one of LOG_USER, LOG_MAIL, LOG_LOCAL0-7. Default facility is LOG_USER. Syslog logging is disabled by default.

alias [file]
  - Replaces local recipients with addresses from the aliases file. The file contains 'local: someone@example.com, person@domain.example' mappings. Comments start with '#'. The 'default' alias is used if a local address is not found. Alias expansion only affects the mail envelope, not headers. An empty argument disables replacement (default).

auto_from [(on|off)]
  - Obsolete; use 'from' command substitution patterns. Enables or disables automatic envelope-from addresses. Default is 'off'. When enabled, generates 'user@domain' envelope-from. Local part is USER, LOGNAME, or login name. Domain part is set by 'maildomain'.

maildomain [domain]
  - Obsolete; use 'from' command substitution patterns. Sets the domain part for envelope-from address generation.
```

--------------------------------

### Store Password in Gnome Key Ring

Source: https://marlam.de/msmtp/msmtp

Demonstrates using the 'secret-tool' command to store an SMTP password securely in the Gnome key ring. This method requires libsecret.

```bash
$ secret-tool store --label=msmtp \
  host mail.freemail.example \
  service smtp \
  user joe.smith
```

--------------------------------

### Configure msmtpd with Encrypted Password

Source: https://marlam.de/msmtp/msmtp

Shows how to configure msmtpd to use an encrypted password file, specifically using gpg for decryption. This approach enhances security by keeping the password encrypted at rest.

```shell
msmtpd ... --auth=msmtpd-user,'gpg -q -d ~/.msmtpd-password.gpg'
```

--------------------------------

### msmtp: Header Handling Options

Source: https://marlam.de/msmtp/msmtp

Controls how various email headers (From, Date, Message-ID, To) are handled, including whether they are set automatically, manually, or omitted. Also includes an option to remove Bcc headers.

```APIDOC
msmtp Options: Header Handling

--set-from-header[=(auto|on|off)]
  Set From header handling. See [set_from_header](#set_005ffrom_005fheader).

--set-date-header[=(auto|off)]
  Set Date header handling. See [set_date_header](#set_005fdate_005fheader).

--set-msgid-header[=(auto|off)]
  Set Message-ID header handling. See [set_msgid_header](#set_005fmsgid_005fheader).

--set-to-header[=(on|off|undisclosed_recipients)]
  Set To header handling. See [set_to_header](#set_005fto_005fheader).

--remove-bcc-headers[=(on|off)]
  Enable or disable the removal of Bcc headers. See [remove_bcc_headers](#remove_005fbcc_005fheaders).
```

--------------------------------

### msmtp: Envelope From Address Options

Source: https://marlam.de/msmtp/msmtp

Configures the envelope-from address for outgoing emails. Includes options to set the address directly, read it from headers, or handle it automatically. Also covers setting a full name for the From header.

```APIDOC
msmtp Options: Envelope From Address

-f address
--from=address
  Set the envelope-from address. If no account is chosen, this option selects the first account matching the given envelope-from address. If no such account is found, 'default' is used.

-Fname
  Set a full name to be used in a From header if msmtp adds one.

--read-envelope-from
  Read the envelope from address from the From header of the mail, or from Resent-From if present and before any From header. Supports '%F' pattern in the envelope from address.

--auto-from[=(on|off)]
  Obsolete. See [auto_from](#auto_005ffrom).
```

--------------------------------

### msmtp Delivery Status Notification (DSN) Configuration

Source: https://marlam.de/msmtp/msmtp

Configures the conditions under which Delivery Status Notification (DSN) messages are sent and how much of the mail content is returned in these notifications. Requires SMTP server support for the DSN extension.

```APIDOC
dsn_notify (off|condition)
  Set the condition(s) under which the mail system should send DSN messages.
  'off' disables explicit DSN requests (default).
  Conditions: 'never', 'failure', 'delay', 'success'. Multiple conditions can be comma-separated.
```

```APIDOC
dsn_return (off|amount)
  Controls how much of a mail should be returned in DSN messages.
  'off' disables explicit DSN requests (default).
  Amount: 'headers' (return only headers) or 'full' (return the full mail).
```

--------------------------------

### msmtp: Recipient and End-of-Options

Source: https://marlam.de/msmtp/msmtp

Defines how recipients are processed and marks the end of command-line options. Includes an option to include recipients from email headers and a special marker for argument parsing.

```APIDOC
msmtp Options: Recipient and End-of-Options

-t
--read-recipients
  Send the mail to the recipients given in the To, Cc, and Bcc headers of the mail in addition to recipients given on the command line. If Resent- headers are present, addresses from Resent-To, Resent-Cc, and Resent-Bcc headers are used instead.

--
  This marks the end of options. All following arguments will be treated as recipient addresses, even if they start with a '-'.

--aliases=[file]
  Set or unset an aliases file. See [aliases](#aliases).

--maildomain=[domain]
  Obsolete. See [maildomain](#maildomain).
```

--------------------------------

### msmtp: DSN Notification Options

Source: https://marlam.de/msmtp/msmtp

Manages Delivery Status Notification (DSN) settings. Allows enabling or disabling notifications and specifying the conditions or amount of information to be returned.

```APIDOC
msmtp Options: DSN Notifications

-N (off|condition)
--dsn-notify=(off|condition)
  Set or unset DSN notification conditions. See [dsn_notify](#dsn_005fnotify).

-R (off|amount)
--dsn-return=(off|amount)
  Set or unset the DSN notification amount. 'hdrs' is accepted as an alias for 'headers' for sendmail compatibility.
```

--------------------------------

### msmtp: Exit Codes

Source: https://marlam.de/msmtp/msmtp

Specifies that msmtp uses standard exit codes from `sysexits.h` for reporting its operational status.

```APIDOC
msmtp Exit Codes:

The standard exit codes from `sysexits.h` are used.
```

--------------------------------

### Configure mail client to use msmtp

Source: https://marlam.de/msmtp/msmtp

Sets the default sendmail program for the 'mail' client to use msmtp. This ensures that emails sent via the 'mail' command are processed by msmtp.

```mailrc
set sendmail="/path/to/msmtp"
```

--------------------------------

### Store Password in Mac OS X Keychain

Source: https://marlam.de/msmtp/msmtp

Illustrates how to store an SMTP password in the Mac OS X Keychain using the 'security' command. This is a platform-specific method for secure password storage.

```bash
security add-internet-password -s mail.freemail.example -r smtp -a joe.smith -w
```

--------------------------------

### msmtp Delivery Status Notification (DSN) Configuration

Source: https://marlam.de/msmtp/msmtp

Controls how and when Delivery Status Notification (DSN) messages are generated for email delivery events like failures or delays. It allows customization of the notification content based on RFC 3461.

```APIDOC
dsn_notify:
  Description: Controls when DSN messages are generated.
  Values: never, failure, delay, success
  Example: dsn_notify failure,delay

--dsn-notify:
  Description: Command-line option for dsn_notify.
  Example: --dsn-notify=failure,delay
```

```APIDOC
dsn_return:
  Description: Controls the amount of original mail content in DSN messages.
  Values: headers, full
  Note: 'full' only applies to DSNs indicating delivery failure.
  Example: dsn_return headers

--dsn-return:
  Description: Command-line option for dsn_return.
  Example: --dsn-return=headers
```