/litestar-email

name: litestar-email
description: "Use when working with litestar_email, EmailPlugin, EmailConfig, EmailService, EmailMessage, SMTPConfig, ResendConfig, SendGridConfig, MailgunConfig, SESConfig. Not for marketing APIs — use vendor SDKs."

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]` with `Provide(email_config.provide_service().__aiter__)`

(or `FromDishka[EmailService]` when the project uses Dishka) for direct `EmailService` handler injection.

• 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="noreply@example.com",
    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 |

The dependency and state keys occupy separate namespaces. Change them independently when the application already uses either key:

email_config = EmailConfig(
    backend="memory",
    email_service_dependency_key="email_service",
    email_service_state_key="email_config",
)

Inject `EmailService`

`EmailPlugin.on_app_init()` registers:

• `Provide(config.provide_service, sync_to_thread=False)` under `email_service_dependency_key`;
• `config.signature_namespace` (`BaseEmailBackend`, `EmailConfig`, `EmailMessage`,

`EmailMultiAlternatives`, `EmailService`, `MailgunConfig`, `ResendConfig`, `SESConfig`, `SMTPConfig`, `SendGridConfig`) in Litestar's signature namespace;

• the `EmailConfig` instance under `email_service_state_key` in app state.

Because `EmailConfig.provide_service()` is a synchronous method returning an `AsyncServiceProvider` instance rather than an `async def` generator function, Litestar's default `Provide(config.provide_service, sync_to_thread=False)` injects `AsyncServiceProvider` rather than `EmailService`.

To inject an open `EmailService` with request-scoped connection cleanup, bind `Provide(email_config.provide_service().__aiter__)` on the router, controller, or handler (or use Dishka's `FromDishka[EmailService]`):

from litestar import post
from litestar.di import NamedDependency, Provide
from litestar_email import EmailConfig, EmailMessage, EmailService

email_config = EmailConfig(backend="memory", from_email="noreply@example.com")


@post(
    "/notifications",
    dependencies={"mailer": Provide(email_config.provide_service().__aiter__)},
)
async def send_notification(
    mailer: NamedDependency[EmailService],
) -> dict[str, int]:
    sent = await mailer.send_message(
        EmailMessage(
            subject="Notification",
            body="You have a new notification.",
            to=["recipient@example.com"],
        ),
    )
    return {"sent": sent}

If using the plugin's default dependency directly without overriding `dependencies`, register `signature_types=[AsyncServiceProvider]`, annotate the parameter as `mailer: NamedDependency[AsyncServiceProvider]`, and enter `async with mailer as service:` inside the handler.

If the project uses Dishka, yield `EmailService` from a `Scope.REQUEST` provider and inject `FromDishka[EmailService]`:

from collections.abc import AsyncIterator

from dishka import Provider, Scope
from dishka.integrations.litestar import FromDishka, inject
from litestar import post
from litestar_email import EmailConfig, EmailMessage, EmailService


def build_email_provider(config: EmailConfig) -> Provider:
    async def provide_mailer() -> AsyncIterator[EmailService]:
        async with config.provide_service() as mailer:
            yield mailer

    provider = Provider(scope=Scope.REQUEST)
    provider.provide(provide_mailer)
    return provider


@post("/welcome")
@inject
async def send_welcome(
    email_service: FromDishka[EmailService],
) -> dict[str, int]:
    sent = await email_service.send_message(
        EmailMessage(subject="Welcome", body="Hello!", to=["user@example.com"]),
    )
    return {"sent": sent}

App state does not contain a permanently open `EmailService`. Use `plugin.get_service(app.state