orionis.mail.PendingMail

THE ORIONIS API

Build with clarity.

Explore the building blocks of an async-first Python framework. Every module, class, and method — connected, searchable, and ready to build with.

Explore modules View classes

class documentation

class PendingMail: (source)

Constructor: PendingMail(delivery, options, mailable_builder)

View In Hierarchy

Build independent chains; every fluent call returns a new operation.

A chain never builds a Mailable, renders, reads attachments, or resolves a transport: those steps belong to the asynchronous terminals. Deriving a chain copies its immutable options, so concurrent branches never share recipients.

Method	`__init__`	Bind an immutable declaration to the manager's delivery pipeline.
Method	`_derive`	Detach a configurator's current snapshot into a new chain.
Async Method	`_sendDirect`	Invoke one callback, freeze its declaration, and deliver.
Async Method	`_sendMailable`	Merge reusable declarations with explicit fluent options.
Method	`attach`	Append a deferred storage attachment on an independent chain.
Method	`bcc`	Append hidden recipients on an independent chain.
Method	`cc`	Append carbon-copy recipients on an independent chain.
Method	`fromAddress`	Replace the sender on a new independent chain.
Async Method	`html`	Send literal HTML through the shared preparation pipeline.
Method	`mailer`	Select a mailer on an independent derived chain.
Async Method	`raw`	Send literal plain text through the shared preparation pipeline.
Method	`replyTo`	Append Reply-To mailboxes on an independent chain.
Async Method	`send`	Send a reusable Mailable, an HTML view, or explicit Content.
Method	`subject`	Replace the subject on an independent chain.
Method	`to`	Append visible recipients on an independent chain.
Class Variable	`__slots__`	Undocumented
Instance Variable	`_delivery`	Undocumented
Instance Variable	`_mailable_builder`	Undocumented
Instance Variable	`_options`	Undocumented

def __init__(self, delivery: Delivery, options: MailOptions | None = None, mailable_builder: Callable[[type[Mailable]], Awaitable[Mailable]] | None = None): (source) ¶

Bind an immutable declaration to the manager's delivery pipeline.

Parameters
delivery:`Delivery`	Shared preparation and transport entry point.
options:`MailOptions \| None`	Immutable explicit options for this chain.
mailable_builder:`Callable[[type[Mailable]], Awaitable[Mailable]] \| None`	Optional application-container resolver for Mailable classes.

Returns
`None`	Initialize a chain without performing I/O.

def _derive(self, message: Message) -> PendingMail: (source) ¶

Detach a configurator's current snapshot into a new chain.

Parameters
message:`Message`	Temporary synchronous configurator.

Returns
`PendingMail`	Independent operation with no render or transport side effects.

async def _sendDirect(self, content: Content, callback: object) -> MailResult: (source) ¶

Invoke one callback, freeze its declaration, and deliver.

Parameters
content:`Content`	Already validated content declaration.
callback:`object`	Configurator invoked exactly once and awaited when needed.

Returns
`MailResult`	Shared delivery outcome.

Raises
`MailCompositionException`	If a callback fails or returns anything other than None or itself.

async def _sendMailable(self, mailable: Mailable) -> MailResult: (source) ¶

Merge reusable declarations with explicit fluent options.

Parameters
mailable:`Mailable`	Reusable synchronous declaration, never modified by sending.

Returns
`MailResult`	Shared delivery outcome.

Raises
`MailCompositionException`	If declaration methods fail or do not return their contracted types.

def attach(self, attachment: Attachment) -> PendingMail: (source) ¶

Append a deferred storage attachment on an independent chain.

Parameters
attachment:`Attachment`	Storage attachment declaration.

Returns
`PendingMail`	Derived operation retaining previous attachments.

def bcc(self, addresses: Recipients, name: str | None = None) -> PendingMail: (source) ¶

Append hidden recipients on an independent chain.

Parameters
addresses:`Recipients`	One mailbox or a list/tuple of mailboxes.
name:`str \| None`	Optional name for a single string mailbox only.

Returns
`PendingMail`	Derived operation retaining previous recipients.

def cc(self, addresses: Recipients, name: str | None = None) -> PendingMail: (source) ¶

Append carbon-copy recipients on an independent chain.

Parameters
addresses:`Recipients`	One mailbox or a list/tuple of mailboxes.
name:`str \| None`	Optional name for a single string mailbox only.

Returns
`PendingMail`	Derived operation retaining previous recipients.

def fromAddress(self, address: str | Address, name: str | None = None) -> PendingMail: (source) ¶

Replace the sender on a new independent chain.

Parameters
address:`str \| Address`	Exactly one sender mailbox.
name:`str \| None`	Optional name for a string mailbox only.

Returns
`PendingMail`	Derived operation with an explicit From and transport sender.

async def html(self, html: str, callback: MessageCallback | None = None) -> MailResult: (source) ¶

Send literal HTML through the shared preparation pipeline.

Parameters
html:`str`	Literal HTML, never rendered as a template.
callback:`MessageCallback \| None`	Optional sync or async operation-local configurator.

Returns
`MailResult`	Transport outcome.

Raises
`MailCompositionException`	If the body, callback, or resulting envelope is invalid.
`MailException`	If preparation or transport fails.

def mailer(self, name: str) -> PendingMail: (source) ¶

Select a mailer on an independent derived chain.

Parameters
name:`str`	Central configuration name, not a driver name.

Returns
`PendingMail`	A new operation; resolution remains deferred until sending.

Raises
`MailConfigurationException`	If the name is not a non-empty string.

async def raw(self, text: str, callback: MessageCallback | None = None) -> MailResult: (source) ¶

Send literal plain text through the shared preparation pipeline.

Parameters
text:`str`	Literal text, never rendered as a template.
callback:`MessageCallback \| None`	Optional sync or async operation-local configurator.

Returns
`MailResult`	Transport outcome.

Raises
`MailCompositionException`	If the body, callback, or resulting envelope is invalid.
`MailException`	If preparation or transport fails.

def replyTo(self, addresses: Recipients, name: str | None = None) -> PendingMail: (source) ¶

Append Reply-To mailboxes on an independent chain.

Parameters
addresses:`Recipients`	One mailbox or a list/tuple of mailboxes.
name:`str \| None`	Optional name for a single string mailbox only.

Returns
`PendingMail`	Derived operation retaining previous reply destinations.

@overload

async def send(self, mailable: Mailable | type[Mailable], /) -> MailResult:

@overload

async def send(self, view: str, /, data: Mapping[str, object] | None = None, callback: MessageCallback | None = None) -> MailResult:

@overload

async def send(self, content: Content, /, *, callback: MessageCallback | None = None) -> MailResult:

(source) ¶

Send a reusable Mailable, an HTML view, or explicit Content.

Parameters
value:`Mailable \| type[Mailable] \| str \| Content`	Declaration, resolvable Mailable class, or HTML view identifier.
data:`Mapping[str, object] \| None`	View context, accepted only when value is a string.
callback:`MessageCallback \| None`	Operation-local configurator, not accepted for a Mailable.

Returns
`MailResult`	Confirmed SMTP acceptance or file publication result.

Raises
`MailCompositionException`	If arguments, container resolution, declarations, callbacks, or content are invalid.
`MailException`	If preparation or transport fails.

def subject(self, value: str) -> PendingMail: (source) ¶

Replace the subject on an independent chain.

Parameters
value:`str`	Literal subject, possibly empty.

Returns
`PendingMail`	Derived operation with an explicit subject.

def to(self, addresses: Recipients, name: str | None = None) -> PendingMail: (source) ¶

Append visible recipients on an independent chain.

Parameters
addresses:`Recipients`	One mailbox or a list/tuple of mailboxes.
name:`str \| None`	Optional name for a single string mailbox only.

Returns
`PendingMail`	Derived operation retaining previous recipients.

__slots__: tuple[str, ...] = (source) ¶

Undocumented

_delivery = (source) ¶

Undocumented

_mailable_builder = (source) ¶

Undocumented

_options = (source) ¶

Undocumented