orionis.mail.contracts.IMailManager

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 IMailManager(ABC): (source)

View In Hierarchy

Expose independent composition and centrally configured mail delivery.

Composition methods are synchronous and always return a new operation. Terminal operations are asynchronous and resolve the configured transport only after the message has been prepared.

Method	`attach`	Start an independent chain with a deferred attachment.
Method	`bcc`	Start an independent chain with hidden recipients.
Method	`cc`	Start an independent chain with carbon-copy recipients.
Method	`extend`	Register one sync or async factory for a new driver.
Method	`fromAddress`	Start an independent chain with exactly one sender.
Async Method	`html`	Send literal HTML without template interpretation.
Method	`mailer`	Start an independent chain selecting a named mailer.
Async Method	`raw`	Send literal plain text without template interpretation.
Method	`replyTo`	Start an independent chain with reply destinations.
Async Method	`send`	Send a Mailable, an HTML view, or Content through one pipeline.
Method	`subject`	Start an independent chain with a literal subject.
Method	`to`	Start an independent chain with primary recipients.
Class Variable	`__slots__`	Undocumented

@abstractmethod

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

Start an independent chain with a deferred attachment.

Parameters
attachment:`Attachment`	Storage attachment declaration.

Returns
`PendingMail`	A synchronous independent chain.

Raises
`MailCompositionException`	If the value is not an attachment declaration.

@abstractmethod

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

Start an independent chain with hidden recipients.

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

Returns
`PendingMail`	A synchronous independent chain.

Raises
`MailCompositionException`	If a mailbox is invalid or combined with an ambiguous name.

@abstractmethod

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

Start an independent chain with carbon-copy recipients.

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

Returns
`PendingMail`	A synchronous independent chain.

Raises
`MailCompositionException`	If a mailbox is invalid or combined with an ambiguous name.

@abstractmethod

def extend(self, driver: str, factory: TransportFactory): (source) ¶

Parameters
driver:`str`	Unique transport implementation name.
factory:`TransportFactory`	Callable receiving the application and the normalized configuration and returning an IMailTransport or an awaitable of one.

Returns
`None`	Register lazily without constructing a transport.

Raises
`MailConfigurationException`	If the name or factory is invalid or the driver already exists.

@abstractmethod

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

Start an independent chain with exactly one sender.

Parameters
address:`str \| Address`	From header and transport sender.
name:`str \| None`	Optional display name, valid only with a string address.

Returns
`PendingMail`	A synchronous chain without I/O.

Raises
`MailCompositionException`	If the mailbox is invalid or a name is supplied twice.

@abstractmethod

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

Send literal HTML without template interpretation.

Parameters
html:`str`	Literal HTML, possibly empty.
callback:`MessageCallback \| None`	Optional operation-local configurator.

Returns
`MailResult`	Transport outcome.

Raises
`MailException`	If configuration, preparation, or transport fails.

@abstractmethod

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

Start an independent chain selecting a named mailer.

Parameters
name:`str`	Configuration name, not a transport driver name.

Returns
`PendingMail`	A synchronous chain with lazy transport resolution.

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

@abstractmethod

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

Send literal plain text without template interpretation.

Parameters
text:`str`	Literal text, possibly empty.
callback:`MessageCallback \| None`	Optional operation-local configurator.

Returns
`MailResult`	Transport outcome.

Raises
`MailException`	If configuration, preparation, or transport fails.

@abstractmethod

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

Start an independent chain with reply destinations.

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

Returns
`PendingMail`	A synchronous independent chain.

Raises
`MailCompositionException`	If a mailbox is invalid or combined with an ambiguous name.

@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:

@abstractmethod

(source) ¶

Send a Mailable, an HTML view, or Content through one pipeline.

Parameters
value:`Mailable \| type[Mailable] \| str \| Content`	A Mailable instance or class, an HTML view name, or explicit content.
data:`Mapping[str, object] \| None`	Explicit view data, allowed only with a string view name.
callback:`MessageCallback \| None`	Sync or async Message configurator, forbidden with a Mailable.

Returns
`MailResult`	Confirmed acceptance, partial acceptance, or file storage.

Raises
`MailException`	If configuration, preparation, or transport fails.

@abstractmethod

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

Start an independent chain with a literal subject.

Parameters
value:`str`	Subject without control characters.

Returns
`PendingMail`	A synchronous independent chain.

Raises
`MailCompositionException`	If the subject is not text or contains control characters.

@abstractmethod

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

Start an independent chain with primary recipients.

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

Returns
`PendingMail`	A synchronous independent chain.

Raises
`MailCompositionException`	If a mailbox is invalid or combined with an ambiguous name.

__slots__: tuple = (source) ¶

Undocumented