Configuration
The Configuration File
outgoing reads information on what sending method and parameters to use
from a TOML or JSON configuration file. The default configuration file is
TOML, and its location depends on your OS:
Linux |
|
macOS |
|
Windows |
|
Changed in version 0.5.0: Due to an upgrade to v3 of platformdirs, the default configuration path
on macOS changed from ~/Library/Preferences/outgoing/outgoing.toml
to ~/Library/Application Support/outgoing/outgoing.toml.
To find the exact path on your system, after installing outgoing, run:
python3 -c "from outgoing import get_default_configpath; print(get_default_configpath())"
Within the configuration file, all of the outgoing settings are contained
within a table named “outgoing”. This table must include at least a
method key giving the name of the sending method to use. The rest of the
table depends on the method chosen (see below). Unknown or inapplicable keys
in the table are ignored.
File & directory paths in the configuration file may start with a tilde (~)
to refer to a path in the user’s home directory. Any relative paths are
resolved relative to the directory containing the configuration file.
Sending Methods
command
The command method sends an e-mail by passing it as input to a command
(e.g., sendmail, sold separately).
Configuration fields:
commandstring or list of strings (optional)Specify the command to run to send e-mail. This can be either a single command string that will be interpreted by the shell or a list of command arguments that will be executed directly without any shell processing. The default command is
sendmail -i -t.Note
Relative paths in the command will not be resolved by
outgoing(unlike other paths in the configuration file), as it is not possible to reliably determine what is a path and what is not.
Example command configuration:
[outgoing]
method = "command"
command = ["/usr/local/bin/mysendmail", "-i", "-t"]
Another sample configuration:
[outgoing]
method = "command"
# A single string will be interpreted by the shell, so metacharacters like
# pipes have their special meanings:
command = "my-mail-munger | ~/some/dir/mysendmail"
smtp
The smtp method sends an e-mail to a server over SMTP.
Configuration fields:
hoststring (required)The domain name or IP address of the server to connect to
sslboolean or"starttls"(optional)true: Use SSL/TLS from the start of the connectionfalse(default): Don’t use SSL/TLS"starttls": After connecting, switch to SSL/TLS with the STARTTLS command
portinteger (optional)The port on the server to connect to; the default depends on the value of
ssl:true— 465false— 25"starttls"— 587
usernamestring (optional)Username to log into the server with
passwordpassword (optional)Password to log into the server with; can be given as either a string or a password specifier (see “Passwords”)
netrcboolean or filepath (optional)If
true, read the username & password from~/.netrcinstead of specifying them in the configuration file. If a filepath, read the credentials from the given netrc file. Iffalse, do not use a netrc file.
Example smtp configuration:
[outgoing]
method = "smtp"
host = "mx.example.com"
ssl = "starttls"
username = "myname"
password = { "file" = "~/secrets/smtp-password" }
Another sample configuration:
[outgoing]
method = "smtp"
host = "mail.nil"
port = 1337
ssl = true
# Read username & password from the "mail.nil" entry in this netrc file:
netrc = "~/secrets/net.rc"
mbox
The mbox method appends e-mails to an mbox file on the local machine.
Configuration fields:
pathfilepath (required)The location of the mbox file. If the file does not exist, it will be created when the sender object is entered.
Example mbox configuration:
[outgoing]
method = "mbox"
path = "~/MAIL/inbox"
maildir
The maildir method adds e-mails to a Maildir mailbox directory on the local
machine.
Configuration fields:
pathdirectory path (required)The location of the Maildir mailbox. If the directory does not exist, it will be created when the sender object is entered.
folderstring (optional)A folder within the Maildir mailbox in which to place e-mails
mh
The mh method adds e-mails to an MH mailbox directory on the local machine.
Configuration fields:
pathdirectory path (required)The location of the MH mailbox. If the directory does not exist, it will be created when the sender object is entered.
folderstring or list of strings (optional)A folder within the Maildir mailbox in which to place e-mails; can be either the name of a single folder or a path through nested folders & subfolders
Example configuration:
[outgoing]
method = "mh"
path = "~/mail"
# Place e-mails inside the "work" folder inside the "important" folder:
folder = ["important", "work"]
mmdf
The mmdf method adds e-mails to an MMDF mailbox file on the local machine.
Configuration fields:
pathfilepath (required)The location of the MMDF mailbox. If the file does not exist, it will be created when the sender object is entered.
babyl
The babyl method adds e-mails to a Babyl mailbox file on the local machine.
Configuration fields:
pathfilepath (required)The location of the Babyl mailbox. If the file does not exist, it will be created when the sender object is entered.
null
Goes nowhere, does nothing, ignores all configuration keys.
Example null configuration:
[outgoing]
# Just send my e-mails into a black hole
method = "null"
Passwords
When a sending method calls for a password, API key, or other secret, there are several ways to specify the value.
Using a string, naturally, supplies the value of that string as the password:
password = "hunter2"
Alternatively, passwords may instead be looked up in external resources. This is done by setting the value of the password field to a table with a single key-value pair, where the key identifies the password lookup scheme and the value is either a string or a sub-table, depending on the scheme.
The builtin password schemes are as follows. Extension packages can define additional password schemes.
base64
For slightly more security than a plaintext password, a password can be stored
in base64 by specifying a table with a single base64 key and the encoded
password as the value:
password = { base64 = "aHVudGVyMg==" }
Base64 passwords must decode to UTF-8 text.
file
A password can be read from a file by specifying a table with a single file
key and the filepath as the value:
password = { file = "path/to/file" }
The entire contents of the file, minus any leading or trailing whitespace, will then be used as the password. As with paths elsewhere in the configuration file, the path may start with a tilde, and relative paths are resolved relative to the directory containing the configuration file.
env
A password can be read from an environment variable by specifying a table with
a single env key and the name of the environment variable as the value:
password = { env = "PROTOCOL_PASSWORD" }
dotenv
Passwords can be read from a key in a .env-style file as supported by
python-dotenv like so:
password = { dotenv = { key = "NAME_OF_KEY_IN_FILE", file = "path/to/file" } }
The file path is resolved following the same rules as other paths. If the
file field is omitted, the given key will be looked up in a file named
.env in the same directory as the configuration file.
keyring
Passwords can be retrieved from the system keyring using keyring. The basic format is:
password = { keyring = { service = "host_or_service_name", username = "your_username" } }
If the service key is omitted, the value will default to the sending
method’s host value, if it has one; likewise, an omitted username will
default to the username for the sending method, if there is one. A specific
keyring backend can be specified with the backend key, and the directory
from which to load the backend can be specified with the keyring-path key.