litestar-email

litestar-email

litestar-email 0.4.0 provides one async sending interface for console, memory, SMTP, Resend, SendGrid, Mailgun, Amazon SES, and custom backends. Match the backend already selected by the project; keep message construction independent from the transport.

Code Style Rules

• Use NamedDependency[EmailService] for handler injection. The plugin registers a named Litestar dependency, not a global service singleton.
• Pass recipient collections as list[str]. to, cc, bcc, and reply_to are list fields.
• Pass attachment content as bytes. Do file I/O before constructing the message and keep that I/O async.
• Await send_message() and send_messages(). Both return the count sent.
• Keep API keys and SMTP credentials in the project's settings layer.

Quick Reference

Install

pip install "litestar-email>=0.4.0"
pip install "litestar-email[smtp]>=0.4.0"   # aiosmtplib
pip install "litestar-email[ses]>=0.4.0"    # botocore for SigV4
pip install "litestar-email[httpx]>=0.4.0"   # default HTTP transport
pip install "litestar-email[aiohttp]>=0.4.0" # alternative HTTP transport

The HTTP API backends select httpx by default, but the transport is optional in litestar-email itself. Install the httpx or aiohttp extra (unless the project already provides that dependency), and select aiohttp only when the project standardizes on it.

Configure the Plugin

from os import environ

from litestar import Litestar
from litestar_email import EmailConfig, EmailPlugin, SMTPConfig

email_config = EmailConfig(
    backend=SMTPConfig(
        host="smtp.example.com",
        port=587,
        username=environ["SMTP_USERNAME"],
        password=environ["SMTP_PASSWORD"],
        use_tls=True,
    ),
    from_email="[email protected]",
    from_name="Example App",
)

app = Litestar(plugins=[EmailPlugin(config=email_config)])

EmailConfig fields:

Field	Default	Contract
backend	"console"	Registered name, import path, or built-in backend config object
from_email	"noreply@localhost"	Default sender address
from_name	""	Default display name
fail_silently	False	Backend-specific best-effort delivery behavior
email_service_dependency_key	"mailer"	Litestar DI key
email_service_state_key	"mailer"	Key holding the config in app state