Core Python API


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[source]

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.

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

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.


InvalidConfigError – if the configuration is invalid

outgoing.get_default_configpath() Path[source]

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

Sender Objects

class outgoing.Sender[source]

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[source]
__exit__(exc_type: type[BaseException] | None, exc_val: BaseException | None, exc_tb: TracebackType | None) bool | None[source]
send(msg: EmailMessage) Any[source]

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.


exception outgoing.Error[source]

Bases: Exception

The superclass for all exceptions raised by outgoing

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

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)[source]

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]])[source]

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[source]

Bases: Error

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

exception outgoing.UnsupportedEmailError[source]

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