E-mail¶

Transactional e-mail over SMTP, with TLS: the messages, their senders, and what's raised when one isn't sent. In fastapi_alcazaba.mail.

In the guide: E-mail.

fastapi_alcazaba.mail.FastAPIMail ¶

FastAPIMail(sender: MailSender, *, from_address: str, reply_to: str | None = None, metrics: Metrics | None = None)

Builds the messages and sends them through sender.

Parameters:

Name	Type	Description	Default
`sender`	`MailSender`	where they go: an `SMTPSender`, or `MemoryMailSender` in tests.	required
`from_address`	`str`	the `From` of every message (`"Example <no-reply@example.com>"`).	required
`reply_to`	`str \| None`	the address replies go to, when it isn't `from_address`.	`None`
`metrics`	`Metrics \| None`	where to count the messages (`fastapi_alcazaba.mail`), by outcome; FastAPICache's by default.	`None`

message ¶

message(to: str | Sequence[str], subject: str, text: str, *, html: str | None = None, headers: Mapping[str, str] | None = None) -> EmailMessage

The message, to to (an address or a few), with text and html as alternatives; headers adds others (List-Unsubscribe...), never those of the sender or the recipients. Raises ValueError for what would forge a header or a recipient.

send `async` ¶

send(to: str | Sequence[str], subject: str, text: str, *, html: str | None = None, headers: Mapping[str, str] | None = None) -> str

Build and send a message (see message); its Message-ID. Raises MailNotSent when it isn't sent.

fastapi_alcazaba.mail.SMTPSender ¶

SMTPSender(host: str, port: int = 587, *, username: str | None = None, password: str | SecretStr | None = None, tls: str = 'starttls', timeout: float = 10.0, ssl_context: SSLContext | None = None)

Sends over SMTP, in a thread, a connection each message, always encrypted: STARTTLS on port 587 (the default), implicit TLS with tls="implicit" (port 465). The server's certificate is checked against the system's authorities; plain SMTP is only for localhost (tls="none": a development server such as Mailpit).

Parameters:

Name	Type	Description	Default
`host`	`str`	the SMTP server.	required
`port`	`int`	its port: 587 for STARTTLS, 465 for implicit TLS.	`587`
`username`	`str \| None`	the account (an SES SMTP user, `apikey` for SendGrid...); None for none.	`None`
`password`	`str \| SecretStr \| None`	its password (a SecretStr from your settings).	`None`
`tls`	`str`	"starttls", "implicit", or "none" for localhost.	`'starttls'`
`timeout`	`float`	seconds for each step of the conversation.	`10.0`
`ssl_context`	`SSLContext \| None`	the TLS context, for a server with an authority of its own.	`None`

fastapi_alcazaba.mail.MemoryMailSender ¶

MemoryMailSender(maxlen: int | None = 1000)

Keeps the last maxlen messages in messages, sending nothing: for tests, and to look at them while developing.

fastapi_alcazaba.mail.MailSender ¶

Bases: Protocol

Where messages go: send gets each one, whole, and raises MailNotSent when it isn't sent.

fastapi_alcazaba.mail.MailNotSent ¶

Bases: Exception

The message wasn't sent: the server refused it, didn't answer, or the TLS failed. Its recipients are in the message; its body never is.