Skip to content

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, simple or relaxed; None keeps 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; None keeps the signer's default.

  • body_show_length (bool | None) –

    Whether the signature says how many body octets it covers; None keeps the signer's default.

default_options

default_options() -> DkimOptions

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; None keeps 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.

is_configured

is_configured() -> bool

Tell whether the envelope of every email is to be changed.

MailerBundle

Bases: Bundle[MailerConfig]

Wires the mailer, its transports, its listeners and its command to the container.

prepend_extension

prepend_extension(builder: ContainerBuilder) -> None

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

process(builder: ContainerBuilder) -> None

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 a failover(...) / roundrobin(...) group of them. It carries credentials, so pass it through env("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 its X-Transport header 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; None signs nothing.

  • smime_signer (SmimeSignerConfig | None) –

    Signs every email with S/MIME; None signs nothing.

  • smime_encrypter (SmimeEncrypterConfig | None) –

    Encrypts each email asking for it with S/MIME; None encrypts nothing.

  • http_client (str | None) –

    The qualifier of the HTTP client provider transports are reached through; None means the default one. Naming one while the xtr-http-client bundle is not active is refused at build.

get_transports

get_transports() -> dict[str, TransportConfig]

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.SmimeCertificateRepositoryInterface service 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-cbc or aes-256-cbc.

  • on_missing_certificate (str) –

    What to do with a recipient without a certificate: fail refuses the email, encrypt sends it unreadable to that recipient, skip drops 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; None for none.

TrackingConfig dataclass

TrackingConfig(opens: bool | None = None, clicks: bool | None = None)

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; None keeps the provider's default.

  • clicks (bool | None) –

    Whether clicks are tracked; None keeps the provider's default.

is_configured

is_configured() -> bool

Tell whether every email asks for tracking one way or the other.

TransportConfig dataclass

TransportConfig(dsn: str, rate_limiter: str | None = None)

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 through env("..."); 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; None caps nothing. A group is never capped: one named for a failover(...) or roundrobin(...) group is refused when the transports are built, at the first email.