Core Python API

Functions

outgoing provides the following functions for constructing e-mail sender objects. Once you have a sender object, simply use it in a context manager to open it up, and then call its send() method with each email.message.EmailMessage object you want to send. See Examples for examples.

outgoing.from_config_file(path: str | bytes | PathLike[str] | PathLike[bytes] | None = None, section: str | None = 'outgoing', fallback: bool = True) → Sender

Read configuration from the table/field section (default “outgoing”) in the file at path (default: the path returned by get_default_configpath()) and construct a sender object from the specification. The file may be either TOML or JSON (type detected based on file extension). If section is None, the entire file, rather than only a single field, is used as the configuration. If fallback is true, the file is not the default config file, and the file either does not exist or does not contain the given section, fall back to reading from the default section of the default config file.

Raises:

• InvalidConfigError – if the configuration is invalid

• MissingConfigError – if no configuration file or section is present

outgoing.from_dict(data: Mapping[str, Any], configpath: str | bytes | PathLike[str] | PathLike[bytes] | None = None) → Sender

Construct a sender object using the given data as the configuration. If configpath is given, any paths in the data will be resolved relative to configpath’s parent directory; otherwise, they will be resolved relative to the current directory.

data should not contain a "configpath" key; such an entry will be discarded.

Raises:

InvalidConfigError – if the configuration is invalid

outgoing.get_default_configpath() → Path

Returns the location of the default config file (regardless of whether it exists) as a pathlib.Path object

Sender Objects

class outgoing.Sender

Sender is a Protocol implemented by sender objects. The protocol requires the following behavior:

• Sender objects can be used as context managers, and their __enter__ methods return self.

• Within its own context, calling a sender’s send(msg: email.message.EmailMessage) method sends the given e-mail.

__enter__() → Self

__exit__(exc_type: type[BaseException] | None, exc_val: BaseException | None, exc_tb: TracebackType | None) → bool | None

send(msg: EmailMessage) → Any

Send msg or raise an exception if that’s not possible

In addition to the base protocol, outgoing’s built-in senders are reentrant and reusable as context managers, and their send() methods can be called outside of a context.

Exceptions

exception outgoing.Error

Bases: Exception

The superclass for all exceptions raised by outgoing

exception outgoing.InvalidConfigError(details: str, configpath: str | bytes | PathLike[str] | PathLike[bytes] | None = None)

Bases: Error

Raised on encountering an invalid configuration structure

configpath: str | bytes | PathLike[str] | PathLike[bytes] | None

The path to the config file containing the invalid configuration

details: str

A message about the error

exception outgoing.InvalidPasswordError(details: str, configpath: str | bytes | PathLike[str] | PathLike[bytes] | None = None)

Bases: InvalidConfigError

Raised on encountering an invalid password specifier or when no password can be determined from a specifier

exception outgoing.MissingConfigError(configpaths: Sequence[str | bytes | PathLike[str] | PathLike[bytes]])

Bases: Error

Raised when no configuration section can be found in any config files

configpaths: list[str | bytes | PathLike[str] | PathLike[bytes]]

Paths to the configfiles searched for configuration

exception outgoing.NetrcLookupError

Bases: Error

Raised by lookup_netrc() on failure to find a match in a netrc file

exception outgoing.UnsupportedEmailError

Bases: Error

Raised by sender objects when asked to send an e-mail that uses features or constructs that the sending method does not support