xtr_mailer.bundle ¶
The mailer bundle and its configuration.
Needs xtr-dependency-injection, which an application installs to list the bundle.
DkimSignerConfig
dataclass
¶
DkimSignerConfig(key: str, domain: str, select: str, passphrase: str = '', header_canon: str | None = None, body_canon: str | None = None, headers_to_ignore: Sequence[str] | None = None, body_show_length: bool | None = None)
Signs every email with DKIM. Needs the dkim extra.
The key is opened when the first email is signed, not when the application starts: pass it
through env("..."), and the console still runs without it.
Attributes:
-
key(str) –The private key as PEM text, or
file://and the path of a PEM file. Never shown. -
domain(str) –The signing domain, the signature's
d=tag. -
select(str) –The selector the public key is published under, its
s=tag. -
passphrase(str) –The passphrase of an encrypted key; empty for one that is not. Never shown.
-
header_canon(str | None) –How headers are canonicalized,
simpleorrelaxed;Nonekeeps the signer's default. -
body_canon(str | None) –How the body is canonicalized, the same way.
-
headers_to_ignore(Sequence[str] | None) –The names of the headers left out of the signature;
Nonekeeps the signer's default. -
body_show_length(bool | None) –Whether the signature says how many body octets it covers;
Nonekeeps the signer's default.
default_options ¶
Return the options the signer uses for every email: those set here.
EnvelopeConfig
dataclass
¶
EnvelopeConfig(sender: str | None = None, recipients: Sequence[str] = (), allowed_recipients: Sequence[str] = ())
The sender and recipients every email is delivered for, in place of its own.
Buildable with no arguments: then every email keeps the envelope its headers give.
Attributes:
-
sender(str | None) –The envelope sender of every email — where bounces go;
Nonekeeps each email's own.Name <address>is read as such. -
recipients(Sequence[str]) –The only recipients every email is delivered to — on a staging server, say; empty keeps each email's own.
-
allowed_recipients(Sequence[str]) –Regular expressions in Python syntax, each matched against a whole recipient address; an email's own recipient one matches is delivered to as well as
recipients.
MailerBundle ¶
Bases: Bundle[MailerConfig]
Wires the mailer, its transports, its listeners and its command to the container.
prepend_extension ¶
Give the logging bundle, when it is active, the channel the mailer logs to.
load_extension ¶
load_extension(config: MailerConfig, services: ServiceConfigurator, builder: ContainerBuilder) -> None
Register the mailer and its transports, and wire each active peer.
Raises:
-
LogicError–A transport is capped by a rate limiter without the rate limiter bundle, an HTTP client is named without the HTTP client bundle, an option needs the event dispatcher bundle and it is inactive, or signing or encrypting is configured without its extra.
process ¶
Offer the factories tagged :data:MAILER_TRANSPORT_FACTORY_TAG to the transports.
MailerConfig
dataclass
¶
MailerConfig(dsn: str | None = None, transports: Mapping[str, str | TransportConfig] = _no_transports(), envelope: EnvelopeConfig = EnvelopeConfig(), headers: Mapping[str, str | Sequence[str]] = _no_headers(), tracking: TrackingConfig = TrackingConfig(), dkim_signer: DkimSignerConfig | None = None, smime_signer: SmimeSignerConfig | None = None, smime_encrypter: SmimeEncrypterConfig | None = None, http_client: str | None = None)
Values the bundle builds the mailer, its transports and its listeners from.
Buildable with no arguments: the zero-config mailer sends through null://null, which
discards every email, so it builds, boots and sends with nothing configured.
Attributes:
-
dsn(str | None) –The one transport, named
main: a DSN, or afailover(...)/roundrobin(...)group of them. It carries credentials, so pass it throughenv("MAILER_DSN"); it is never shown, and read when the first email is sent. -
transports(Mapping[str, str | TransportConfig]) –Named transports instead, each a DSN or a :class:
TransportConfig; an email goes through the first unless itsX-Transportheader names another. -
envelope(EnvelopeConfig) –The sender and recipients every email is delivered for.
-
headers(Mapping[str, str | Sequence[str]]) –Headers every email gets, by name — a value, or several for an address list.
-
tracking(TrackingConfig) –Whether a provider tracks the opens and clicks of every email.
-
dkim_signer(DkimSignerConfig | None) –Signs every email with DKIM;
Nonesigns nothing. -
smime_signer(SmimeSignerConfig | None) –Signs every email with S/MIME;
Nonesigns nothing. -
smime_encrypter(SmimeEncrypterConfig | None) –Encrypts each email asking for it with S/MIME;
Noneencrypts nothing. -
http_client(str | None) –The qualifier of the HTTP client provider transports are reached through;
Nonemeans the default one. Naming one while the xtr-http-client bundle is not active is refused at build.
get_transports ¶
Return every transport by name, in order: main alone for a single DSN.
SmimeEncrypterConfig
dataclass
¶
SmimeEncrypterConfig(repository: Reference | None = None, certificates: Mapping[str, str] = _no_certificates(), cipher: str = SMimeEncrypter.CIPHER_AES_256_CBC, on_missing_certificate: str = FAIL, encrypt_for_sender: bool = False)
Encrypts each email carrying an X-SMime-Encrypt header. Needs the smime extra.
The recipients' certificates come from certificates, or from a repository service the
application registers — one or the other.
Attributes:
-
repository(Reference | None) –The :class:
~xtr_mailer.event_listener.SmimeCertificateRepositoryInterfaceservice finding each recipient's certificate, by its type and qualifier. -
certificates(Mapping[str, str]) –The path of each recipient's certificate, by address.
-
cipher(str) –aes-128-cbcoraes-256-cbc. -
on_missing_certificate(str) –What to do with a recipient without a certificate:
failrefuses the email,encryptsends it unreadable to that recipient,skipdrops the recipient. -
encrypt_for_sender(bool) –Encrypt for the envelope sender's certificate too, when there is one, so the sender can read what was sent.
SmimeSignerConfig
dataclass
¶
SmimeSignerConfig(certificate: str, key: str, passphrase: str = '', extra_certificates: str | None = None)
Signs every email with S/MIME. Needs the smime extra.
The certificate and the key are read when the first email is signed, not when the application starts.
Attributes:
-
certificate(str) –The path of the signing certificate's PEM file.
-
key(str) –The path of the PEM file of the certificate's private key.
-
passphrase(str) –The passphrase of an encrypted key; empty for one that is not. Never shown.
-
extra_certificates(str | None) –The path of a PEM file of the intermediate certificates a receiver needs to follow the signing certificate up to one it trusts;
Nonefor none.
TrackingConfig
dataclass
¶
Asks the provider to track opens and clicks, or not, through an X-Track header.
Buildable with no arguments: then each provider keeps its own default. An X-Track
header among the configured headers wins over these, and one set on an email wins over
both.
Attributes:
-
opens(bool | None) –Whether opens are tracked;
Nonekeeps the provider's default. -
clicks(bool | None) –Whether clicks are tracked;
Nonekeeps the provider's default.
is_configured ¶
Tell whether every email asks for tracking one way or the other.
TransportConfig
dataclass
¶
A transport, built from its DSN when the first email is sent.
Attributes:
-
dsn(str) –One DSN, or a
failover(...)/roundrobin(...)group of them. It carries credentials, so pass it throughenv("..."); it is never shown. -
rate_limiter(str | None) –The name of the xtr-rate-limiter limiter each email through the transport takes a token from;
Nonecaps nothing. A group is never capped: one named for afailover(...)orroundrobin(...)group is refused when the transports are built, at the first email.