plain.email 0.13.0__py3-none-any.whl → 0.15.0__py3-none-any.whl

plain/email/CHANGELOG.md

@@ -1,5 +1,26 @@
 # plain-email changelog
 
+## [0.15.0](https://github.com/dropseed/plain/releases/plain-email@0.15.0) (2026-01-15)
+
+### What's changed
+
+- `EMAIL_HOST_PASSWORD` is now marked as a `Secret` type, ensuring the password is masked when displaying settings in CLI output ([7666190](https://github.com/dropseed/plain/commit/7666190305e13ebd1fc9b536e6415e863c2c0b25))
+
+### Upgrade instructions
+
+- No changes required
+
+## [0.14.0](https://github.com/dropseed/plain/releases/plain-email@0.14.0) (2026-01-13)
+
+### What's changed
+
+- Simplified public API exports to only include user-facing classes and functions ([28f4849](https://github.com/dropseed/plain/commit/28f4849ca5692acc1dbef97f1590ddbd2f5afe96))
+- Improved README documentation with comprehensive usage examples and installation instructions ([da37a78](https://github.com/dropseed/plain/commit/da37a78fbb8a683c65863f4d0b7af9af5b16feec))
+
+### Upgrade instructions
+
+- No changes required
+
 ## [0.13.0](https://github.com/dropseed/plain/releases/plain-email@0.13.0) (2025-12-04)
 
 ### What's changed

plain/email/README.md

@@ -1,18 +1,263 @@
 # plain.email
 
-**Everything you need to send email in Plain.**
+**Send emails from your Plain application using SMTP, console output, or file-based backends.**
 
+- [Overview](#overview)
+    - [Sending a simple email](#sending-a-simple-email)
+    - [Sending HTML emails](#sending-html-emails)
+    - [Template-based emails](#template-based-emails)
+    - [Attachments](#attachments)
+- [Configuration](#configuration)
+    - [SMTP settings](#smtp-settings)
+- [Email backends](#email-backends)
+    - [SMTP backend](#smtp-backend)
+    - [Console backend](#console-backend)
+    - [File-based backend](#file-based-backend)
+- [FAQs](#faqs)
 - [Installation](#installation)
 
+## Overview
+
+You can send emails using the `send_mail` function for simple cases, or use the `EmailMessage` and `EmailMultiAlternatives` classes for more control. For template-based emails, the `TemplateEmail` class renders HTML templates automatically.
+
+### Sending a simple email
+
+The `send_mail` function is the easiest way to send an email.
+
+```python
+from plain.email import send_mail
+
+send_mail(
+    subject="Welcome!",
+    message="Thanks for signing up.",
+    from_email="hello@example.com",
+    recipient_list=["user@example.com"],
+)
+```
+
+To include an HTML version along with the plain text:
+
+```python
+send_mail(
+    subject="Welcome!",
+    message="Thanks for signing up.",
+    from_email="hello@example.com",
+    recipient_list=["user@example.com"],
+    html_message="<h1>Thanks for signing up!</h1>",
+)
+```
+
+### Sending HTML emails
+
+For more control over multipart emails, use `EmailMultiAlternatives`.
+
+```python
+from plain.email import EmailMultiAlternatives
+
+email = EmailMultiAlternatives(
+    subject="Your order confirmation",
+    body="Your order #123 has been confirmed.",
+    from_email="orders@example.com",
+    to=["customer@example.com"],
+)
+email.attach_alternative("<h1>Order #123 Confirmed</h1>", "text/html")
+email.send()
+```
+
+### Template-based emails
+
+The `TemplateEmail` class renders emails from template files. You provide a template name, and it looks for corresponding files in your `templates/email/` directory:
+
+- `email/{template}.html` - HTML content (required)
+- `email/{template}.txt` - Plain text content (optional, falls back to stripping HTML tags)
+- `email/{template}.subject.txt` - Subject line (optional)
+
+```python
+from plain.email import TemplateEmail
+
+email = TemplateEmail(
+    template="welcome",
+    context={"user_name": "Alice"},
+    to=["alice@example.com"],
+)
+email.send()
+```
+
+With these template files:
+
+```html
+<!-- templates/email/welcome.html -->
+<h1>Welcome, {{ user_name }}!</h1>
+<p>We're glad you're here.</p>
+```
+
+```text
+{# templates/email/welcome.subject.txt #}
+Welcome to our app, {{ user_name }}!
+```
+
+You can subclass `TemplateEmail` to customize the template context by overriding `get_template_context()`.
+
+### Attachments
+
+You can attach files to any email message.
+
+```python
+from plain.email import EmailMessage
+
+email = EmailMessage(
+    subject="Your report",
+    body="Please find your report attached.",
+    to=["user@example.com"],
+)
+
+# Attach content directly
+email.attach("report.csv", csv_content, "text/csv")
+
+# Or attach a file from disk
+email.attach_file("/path/to/report.pdf")
+
+email.send()
+```
+
+## Configuration
+
+Configure email settings in your `settings.py`:
+
+```python
+# settings.py
+
+# Required: The backend to use for sending emails
+EMAIL_BACKEND = "plain.email.backends.smtp.EmailBackend"
+
+# Required: Default "From" address for outgoing emails
+EMAIL_DEFAULT_FROM = "noreply@example.com"
+
+# Optional: Default "Reply-To" addresses
+EMAIL_DEFAULT_REPLY_TO = ["support@example.com"]
+```
+
+### SMTP settings
+
+When using the SMTP backend, configure your mail server:
+
+```python
+# settings.py
+
+EMAIL_HOST = "smtp.example.com"
+EMAIL_PORT = 587
+EMAIL_HOST_USER = "your-username"
+EMAIL_HOST_PASSWORD = "your-password"
+EMAIL_USE_TLS = True  # Use STARTTLS
+EMAIL_USE_SSL = False  # Use implicit SSL (mutually exclusive with TLS)
+
+# Optional settings
+EMAIL_TIMEOUT = 10  # Connection timeout in seconds
+EMAIL_SSL_CERTFILE = None  # Path to SSL certificate file
+EMAIL_SSL_KEYFILE = None  # Path to SSL key file
+EMAIL_USE_LOCALTIME = False  # Use local time in Date header (default: UTC)
+```
+
+## Email backends
+
+The `EMAIL_BACKEND` setting controls how emails are sent. Plain includes three backends.
+
+### SMTP backend
+
+The default backend sends emails via SMTP.
+
+```python
+EMAIL_BACKEND = "plain.email.backends.smtp.EmailBackend"
+```
+
+### Console backend
+
+Prints emails to the console instead of sending them. Useful during development.
+
+```python
+EMAIL_BACKEND = "plain.email.backends.console.EmailBackend"
+```
+
+### File-based backend
+
+Writes emails to files in a directory. Useful for testing and debugging.
+
+```python
+EMAIL_BACKEND = "plain.email.backends.filebased.EmailBackend"
+EMAIL_FILE_PATH = "/path/to/email-output"
+```
+
+Each email is saved to a timestamped `.log` file in the specified directory.
+
+## FAQs
+
+#### How do I send to multiple recipients efficiently?
+
+Use `send_mass_mail` to send multiple messages over a single connection:
+
+```python
+from plain.email import send_mass_mail
+
+messages = (
+    ("Subject 1", "Body 1", "from@example.com", ["to1@example.com"]),
+    ("Subject 2", "Body 2", "from@example.com", ["to2@example.com"]),
+)
+send_mass_mail(messages)
+```
+
+#### How do I reuse a connection for multiple emails?
+
+Use the backend as a context manager:
+
+```python
+from plain.email import get_connection, EmailMessage
+
+with get_connection() as connection:
+    for user in users:
+        email = EmailMessage(
+            subject="Hello",
+            body="Hi there!",
+            to=[user.email],
+            connection=connection,
+        )
+        email.send()
+```
+
+#### How do I add custom headers?
+
+Pass a `headers` dict to any email class:
+
+```python
+email = EmailMessage(
+    subject="Hello",
+    body="Content",
+    to=["user@example.com"],
+    headers={"X-Custom-Header": "value", "Reply-To": "reply@example.com"},
+)
+```
+
+#### How do I create a custom email backend?
+
+Subclass [`BaseEmailBackend`](./backends/base.py#BaseEmailBackend) and implement the `send_messages` method:
+
+```python
+from plain.email.backends.base import BaseEmailBackend
+
+class MyBackend(BaseEmailBackend):
+    def send_messages(self, email_messages):
+        # Your sending logic here
+        return len(email_messages)
+```
+
 ## Installation
 
-Install the `plain.email` package from [PyPI](https://pypi.org/project/plain.email/):
+Install the `plain.email` package from PyPI:
 
 ```bash
 uv add plain.email
 ```
 
-Add `plain.email` to your `INSTALLED_PACKAGES`:
+Add `plain.email` to your `INSTALLED_PACKAGES` and configure the required settings:
 
 ```python
 # settings.py
@@ -20,4 +265,20 @@ INSTALLED_PACKAGES = [
     # ...
     "plain.email",
 ]
+
+EMAIL_BACKEND = "plain.email.backends.smtp.EmailBackend"
+EMAIL_DEFAULT_FROM = "noreply@example.com"
+
+# For SMTP (adjust for your mail provider)
+EMAIL_HOST = "smtp.example.com"
+EMAIL_PORT = 587
+EMAIL_HOST_USER = "your-username"
+EMAIL_HOST_PASSWORD = "your-password"
+EMAIL_USE_TLS = True
+```
+
+For local development, use the console backend to see emails in your terminal:
+
+```python
+EMAIL_BACKEND = "plain.email.backends.console.EmailBackend"
 ```

plain/email/__init__.py

@@ -13,30 +13,19 @@ if TYPE_CHECKING:
     from .backends.base import BaseEmailBackend
 
 from .message import (
-    DEFAULT_ATTACHMENT_MIME_TYPE,
     BadHeaderError,
     EmailMessage,
     EmailMultiAlternatives,
-    SafeMIMEMultipart,
-    SafeMIMEText,
     TemplateEmail,
-    forbid_multi_line_headers,
     make_msgid,
 )
-from .utils import DNS_NAME, CachedDnsName
 
 __all__ = [
-    "CachedDnsName",
-    "DNS_NAME",
     "EmailMessage",
     "EmailMultiAlternatives",
     "TemplateEmail",
-    "SafeMIMEText",
-    "SafeMIMEMultipart",
-    "DEFAULT_ATTACHMENT_MIME_TYPE",
     "make_msgid",
     "BadHeaderError",
-    "forbid_multi_line_headers",
     "get_connection",
     "send_mail",
     "send_mass_mail",

plain/email/backends/smtp.py

@@ -11,8 +11,8 @@ from typing import TYPE_CHECKING, Any
 from plain.runtime import settings
 
 from ..backends.base import BaseEmailBackend
-from ..message import sanitize_address
-from ..utils import DNS_NAME
+from ..message import _sanitize_address
+from ..utils import _DNS_NAME
 
 if TYPE_CHECKING:
     from ..message import EmailMessage
@@ -84,7 +84,7 @@ class EmailBackend(BaseEmailBackend):
 
         # If local_hostname is not specified, socket.getfqdn() gets used.
         # For performance, we use the cached FQDN for local_hostname.
-        connection_params: dict[str, Any] = {"local_hostname": DNS_NAME.get_fqdn()}
+        connection_params: dict[str, Any] = {"local_hostname": _DNS_NAME.get_fqdn()}
         if self.timeout is not None:
             connection_params["timeout"] = self.timeout
         if self.use_ssl:
@@ -153,9 +153,9 @@ class EmailBackend(BaseEmailBackend):
         if not email_message.recipients():
             return False
         encoding = email_message.encoding or settings.DEFAULT_CHARSET
-        from_email = sanitize_address(email_message.from_email, encoding)
+        from_email = _sanitize_address(email_message.from_email, encoding)
         recipients = [
-            sanitize_address(addr, encoding) for addr in email_message.recipients()
+            _sanitize_address(addr, encoding) for addr in email_message.recipients()
         ]
         message = email_message.message()
         assert self.connection is not None, "connection should be open before sending"

plain/email/default_settings.py

@@ -1,3 +1,5 @@
+from plain.runtime import Secret
+
 # The email backend to use. For possible shortcuts see plain.email.
 # The default is to use the SMTP backend.
 # Third-party backends can be specified by providing a Python path
@@ -19,7 +21,7 @@ EMAIL_USE_LOCALTIME: bool = False
 
 # Optional SMTP authentication information for EMAIL_HOST.
 EMAIL_HOST_USER: str = ""
-EMAIL_HOST_PASSWORD: str = ""
+EMAIL_HOST_PASSWORD: Secret[str] = ""  # type: ignore[assignment]
 EMAIL_USE_TLS: bool = True
 EMAIL_USE_SSL: bool = False
 EMAIL_SSL_CERTFILE: str | None = None

plain/email/message.py

@@ -20,12 +20,13 @@ from io import BytesIO, StringIO
 from pathlib import Path
 from typing import TYPE_CHECKING, Any
 
+from plain.internal import internalcode
 from plain.runtime import settings
 from plain.templates import Template, TemplateFileMissing
 from plain.utils.encoding import force_str, punycode
 from plain.utils.html import strip_tags
 
-from .utils import DNS_NAME
+from .utils import _DNS_NAME
 
 if TYPE_CHECKING:
     from os import PathLike
@@ -34,16 +35,16 @@ if TYPE_CHECKING:
 
 # Don't BASE64-encode UTF-8 messages so that we avoid unwanted attention from
 # some spam filters.
-utf8_charset = Charset.Charset("utf-8")
-utf8_charset.body_encoding = None  # type: ignore[assignment]  # Python defaults to BASE64
-utf8_charset_qp = Charset.Charset("utf-8")
-utf8_charset_qp.body_encoding = Charset.QP
+_utf8_charset = Charset.Charset("utf-8")
+_utf8_charset.body_encoding = None  # type: ignore[assignment]  # Python defaults to BASE64
+_utf8_charset_qp = Charset.Charset("utf-8")
+_utf8_charset_qp.body_encoding = Charset.QP
 
 # Default MIME type to use on attachments (if it is not explicitly given
 # and cannot be guessed).
-DEFAULT_ATTACHMENT_MIME_TYPE = "application/octet-stream"
+_DEFAULT_ATTACHMENT_MIME_TYPE = "application/octet-stream"
 
-RFC5322_EMAIL_LINE_LENGTH_LIMIT = 998
+_RFC5322_EMAIL_LINE_LENGTH_LIMIT = 998
 
 
 class BadHeaderError(ValueError):
@@ -51,7 +52,7 @@ class BadHeaderError(ValueError):
 
 
 # Header names that contain structured address data (RFC 5322).
-ADDRESS_HEADERS = {
+_ADDRESS_HEADERS = {
     "from",
     "sender",
     "reply-to",
@@ -66,7 +67,7 @@ ADDRESS_HEADERS = {
 }
 
 
-def forbid_multi_line_headers(
+def _forbid_multi_line_headers(
     name: str, val: str, encoding: str | None
 ) -> tuple[str, str]:
     """Forbid multi-line headers to prevent header injection."""
@@ -79,9 +80,9 @@ def forbid_multi_line_headers(
     try:
         val.encode("ascii")
     except UnicodeEncodeError:
-        if name.lower() in ADDRESS_HEADERS:
+        if name.lower() in _ADDRESS_HEADERS:
             val = ", ".join(
-                sanitize_address(addr, encoding) for addr in getaddresses((val,))
+                _sanitize_address(addr, encoding) for addr in getaddresses((val,))
             )
         else:
             val = Header(val, encoding).encode()
@@ -91,7 +92,7 @@ def forbid_multi_line_headers(
     return name, val
 
 
-def sanitize_address(addr: str | tuple[str, str], encoding: str) -> str:
+def _sanitize_address(addr: str | tuple[str, str], encoding: str) -> str:
     """
     Format a pair of (name, address) or an email address string.
     """
@@ -135,6 +136,7 @@ def sanitize_address(addr: str | tuple[str, str], encoding: str) -> str:
     return formataddr((nm, parsed_address.addr_spec))
 
 
+@internalcode
 class MIMEMixin:
     def as_string(self, unixfrom: bool = False, linesep: str = "\n") -> str:
         """Return the entire formatted message as a string.
@@ -163,13 +165,15 @@ class MIMEMixin:
         return fp.getvalue()
 
 
+@internalcode
 class SafeMIMEMessage(MIMEMixin, MIMEMessage):
     def __setitem__(self, name: str, val: str) -> None:
         # message/rfc822 attachments must be ASCII
-        name, val = forbid_multi_line_headers(name, val, "ascii")
+        name, val = _forbid_multi_line_headers(name, val, "ascii")
         MIMEMessage.__setitem__(self, name, val)
 
 
+@internalcode
 class SafeMIMEText(MIMEMixin, MIMEText):
     def __init__(
         self, _text: str, _subtype: str = "plain", _charset: str | None = None
@@ -178,7 +182,7 @@ class SafeMIMEText(MIMEMixin, MIMEText):
         MIMEText.__init__(self, _text, _subtype=_subtype, _charset=_charset)
 
     def __setitem__(self, name: str, val: str) -> None:
-        name, val = forbid_multi_line_headers(name, val, self.encoding)
+        name, val = _forbid_multi_line_headers(name, val, self.encoding)
         MIMEText.__setitem__(self, name, val)
 
     def set_payload(  # type: ignore[override]
@@ -186,15 +190,16 @@ class SafeMIMEText(MIMEMixin, MIMEText):
     ) -> None:
         if charset == "utf-8" and not isinstance(charset, Charset.Charset):
             has_long_lines = any(
-                len(line.encode()) > RFC5322_EMAIL_LINE_LENGTH_LIMIT
+                len(line.encode()) > _RFC5322_EMAIL_LINE_LENGTH_LIMIT
                 for line in payload.splitlines()
             )
             # Quoted-Printable encoding has the side effect of shortening long
             # lines, if any (#22561).
-            charset = utf8_charset_qp if has_long_lines else utf8_charset
+            charset = _utf8_charset_qp if has_long_lines else _utf8_charset
         MIMEText.set_payload(self, payload, charset=charset)
 
 
+@internalcode
 class SafeMIMEMultipart(MIMEMixin, MIMEMultipart):
     def __init__(
         self,
@@ -208,7 +213,7 @@ class SafeMIMEMultipart(MIMEMixin, MIMEMultipart):
         MIMEMultipart.__init__(self, _subtype, boundary, _subparts, **_params)
 
     def __setitem__(self, name: str, val: str) -> None:
-        name, val = forbid_multi_line_headers(name, val, self.encoding)
+        name, val = _forbid_multi_line_headers(name, val, self.encoding)
         MIMEMultipart.__setitem__(self, name, val)
 
 
@@ -300,8 +305,8 @@ class EmailMessage:
             # will get picked up by formatdate().
             msg["Date"] = formatdate(localtime=settings.EMAIL_USE_LOCALTIME)
         if "message-id" not in header_names:
-            # Use cached DNS_NAME for performance
-            msg["Message-ID"] = make_msgid(domain=str(DNS_NAME))
+            # Use cached _DNS_NAME for performance
+            msg["Message-ID"] = make_msgid(domain=str(_DNS_NAME))
         for name, value in self.extra_headers.items():
             if name.lower() != "from":  # From is already handled
                 msg[name] = value
@@ -337,7 +342,7 @@ class EmailMessage:
 
         For a text/* mimetype (guessed or specified), when a bytes object is
         specified as content, decode it as UTF-8. If that fails, set the
-        mimetype to DEFAULT_ATTACHMENT_MIME_TYPE and don't decode the content.
+        mimetype to _DEFAULT_ATTACHMENT_MIME_TYPE and don't decode the content.
         """
         if isinstance(filename, MIMEBase):
             if content is not None or mimetype is not None:
@@ -352,7 +357,7 @@ class EmailMessage:
             if filename is not None and mimetype is None:
                 mimetype = mimetypes.guess_type(filename)[0]
             if mimetype is None:
-                mimetype = DEFAULT_ATTACHMENT_MIME_TYPE
+                mimetype = _DEFAULT_ATTACHMENT_MIME_TYPE
             basetype, subtype = mimetype.split("/", 1)
 
             if basetype == "text":
@@ -362,7 +367,7 @@ class EmailMessage:
                     except UnicodeDecodeError:
                         # If mimetype suggests the file is text but it's
                         # actually binary, read() raises a UnicodeDecodeError.
-                        mimetype = DEFAULT_ATTACHMENT_MIME_TYPE
+                        mimetype = _DEFAULT_ATTACHMENT_MIME_TYPE
 
             self.attachments.append((filename, content, mimetype))
 
@@ -372,12 +377,12 @@ class EmailMessage:
         """
         Attach a file from the filesystem.
 
-        Set the mimetype to DEFAULT_ATTACHMENT_MIME_TYPE if it isn't specified
+        Set the mimetype to _DEFAULT_ATTACHMENT_MIME_TYPE if it isn't specified
         and cannot be guessed.
 
         For a text/* mimetype (guessed or specified), decode the file's content
         as UTF-8. If that fails, set the mimetype to
-        DEFAULT_ATTACHMENT_MIME_TYPE and don't decode the content.
+        _DEFAULT_ATTACHMENT_MIME_TYPE and don't decode the content.
         """
         path = Path(path)
         with path.open("rb") as file:

plain/email/utils.py

@@ -6,11 +6,13 @@ from __future__ import annotations
 
 import socket
 
+from plain.internal import internalcode
 from plain.utils.encoding import punycode
 
 
 # Cache the hostname, but do it lazily: socket.getfqdn() can take a couple of
 # seconds, which slows down the restart of the server.
+@internalcode
 class CachedDnsName:
     def __str__(self) -> str:
         return self.get_fqdn()
@@ -21,4 +23,4 @@ class CachedDnsName:
         return self._fqdn
 
 
-DNS_NAME = CachedDnsName()
+_DNS_NAME = CachedDnsName()

plain_email-0.15.0.dist-info/METADATA

@@ -0,0 +1,295 @@
+Metadata-Version: 2.4
+Name: plain.email
+Version: 0.15.0
+Summary: Everything you need to send email in Plain.
+Author-email: Dave Gaeddert <dave.gaeddert@dropseed.dev>
+License-Expression: BSD-3-Clause
+License-File: LICENSE
+Requires-Python: >=3.13
+Requires-Dist: plain<1.0.0
+Description-Content-Type: text/markdown
+
+# plain.email
+
+**Send emails from your Plain application using SMTP, console output, or file-based backends.**
+
+- [Overview](#overview)
+    - [Sending a simple email](#sending-a-simple-email)
+    - [Sending HTML emails](#sending-html-emails)
+    - [Template-based emails](#template-based-emails)
+    - [Attachments](#attachments)
+- [Configuration](#configuration)
+    - [SMTP settings](#smtp-settings)
+- [Email backends](#email-backends)
+    - [SMTP backend](#smtp-backend)
+    - [Console backend](#console-backend)
+    - [File-based backend](#file-based-backend)
+- [FAQs](#faqs)
+- [Installation](#installation)
+
+## Overview
+
+You can send emails using the `send_mail` function for simple cases, or use the `EmailMessage` and `EmailMultiAlternatives` classes for more control. For template-based emails, the `TemplateEmail` class renders HTML templates automatically.
+
+### Sending a simple email
+
+The `send_mail` function is the easiest way to send an email.
+
+```python
+from plain.email import send_mail
+
+send_mail(
+    subject="Welcome!",
+    message="Thanks for signing up.",
+    from_email="hello@example.com",
+    recipient_list=["user@example.com"],
+)
+```
+
+To include an HTML version along with the plain text:
+
+```python
+send_mail(
+    subject="Welcome!",
+    message="Thanks for signing up.",
+    from_email="hello@example.com",
+    recipient_list=["user@example.com"],
+    html_message="<h1>Thanks for signing up!</h1>",
+)
+```
+
+### Sending HTML emails
+
+For more control over multipart emails, use `EmailMultiAlternatives`.
+
+```python
+from plain.email import EmailMultiAlternatives
+
+email = EmailMultiAlternatives(
+    subject="Your order confirmation",
+    body="Your order #123 has been confirmed.",
+    from_email="orders@example.com",
+    to=["customer@example.com"],
+)
+email.attach_alternative("<h1>Order #123 Confirmed</h1>", "text/html")
+email.send()
+```
+
+### Template-based emails
+
+The `TemplateEmail` class renders emails from template files. You provide a template name, and it looks for corresponding files in your `templates/email/` directory:
+
+- `email/{template}.html` - HTML content (required)
+- `email/{template}.txt` - Plain text content (optional, falls back to stripping HTML tags)
+- `email/{template}.subject.txt` - Subject line (optional)
+
+```python
+from plain.email import TemplateEmail
+
+email = TemplateEmail(
+    template="welcome",
+    context={"user_name": "Alice"},
+    to=["alice@example.com"],
+)
+email.send()
+```
+
+With these template files:
+
+```html
+<!-- templates/email/welcome.html -->
+<h1>Welcome, {{ user_name }}!</h1>
+<p>We're glad you're here.</p>
+```
+
+```text
+{# templates/email/welcome.subject.txt #}
+Welcome to our app, {{ user_name }}!
+```
+
+You can subclass `TemplateEmail` to customize the template context by overriding `get_template_context()`.
+
+### Attachments
+
+You can attach files to any email message.
+
+```python
+from plain.email import EmailMessage
+
+email = EmailMessage(
+    subject="Your report",
+    body="Please find your report attached.",
+    to=["user@example.com"],
+)
+
+# Attach content directly
+email.attach("report.csv", csv_content, "text/csv")
+
+# Or attach a file from disk
+email.attach_file("/path/to/report.pdf")
+
+email.send()
+```
+
+## Configuration
+
+Configure email settings in your `settings.py`:
+
+```python
+# settings.py
+
+# Required: The backend to use for sending emails
+EMAIL_BACKEND = "plain.email.backends.smtp.EmailBackend"
+
+# Required: Default "From" address for outgoing emails
+EMAIL_DEFAULT_FROM = "noreply@example.com"
+
+# Optional: Default "Reply-To" addresses
+EMAIL_DEFAULT_REPLY_TO = ["support@example.com"]
+```
+
+### SMTP settings
+
+When using the SMTP backend, configure your mail server:
+
+```python
+# settings.py
+
+EMAIL_HOST = "smtp.example.com"
+EMAIL_PORT = 587
+EMAIL_HOST_USER = "your-username"
+EMAIL_HOST_PASSWORD = "your-password"
+EMAIL_USE_TLS = True  # Use STARTTLS
+EMAIL_USE_SSL = False  # Use implicit SSL (mutually exclusive with TLS)
+
+# Optional settings
+EMAIL_TIMEOUT = 10  # Connection timeout in seconds
+EMAIL_SSL_CERTFILE = None  # Path to SSL certificate file
+EMAIL_SSL_KEYFILE = None  # Path to SSL key file
+EMAIL_USE_LOCALTIME = False  # Use local time in Date header (default: UTC)
+```
+
+## Email backends
+
+The `EMAIL_BACKEND` setting controls how emails are sent. Plain includes three backends.
+
+### SMTP backend
+
+The default backend sends emails via SMTP.
+
+```python
+EMAIL_BACKEND = "plain.email.backends.smtp.EmailBackend"
+```
+
+### Console backend
+
+Prints emails to the console instead of sending them. Useful during development.
+
+```python
+EMAIL_BACKEND = "plain.email.backends.console.EmailBackend"
+```
+
+### File-based backend
+
+Writes emails to files in a directory. Useful for testing and debugging.
+
+```python
+EMAIL_BACKEND = "plain.email.backends.filebased.EmailBackend"
+EMAIL_FILE_PATH = "/path/to/email-output"
+```
+
+Each email is saved to a timestamped `.log` file in the specified directory.
+
+## FAQs
+
+#### How do I send to multiple recipients efficiently?
+
+Use `send_mass_mail` to send multiple messages over a single connection:
+
+```python
+from plain.email import send_mass_mail
+
+messages = (
+    ("Subject 1", "Body 1", "from@example.com", ["to1@example.com"]),
+    ("Subject 2", "Body 2", "from@example.com", ["to2@example.com"]),
+)
+send_mass_mail(messages)
+```
+
+#### How do I reuse a connection for multiple emails?
+
+Use the backend as a context manager:
+
+```python
+from plain.email import get_connection, EmailMessage
+
+with get_connection() as connection:
+    for user in users:
+        email = EmailMessage(
+            subject="Hello",
+            body="Hi there!",
+            to=[user.email],
+            connection=connection,
+        )
+        email.send()
+```
+
+#### How do I add custom headers?
+
+Pass a `headers` dict to any email class:
+
+```python
+email = EmailMessage(
+    subject="Hello",
+    body="Content",
+    to=["user@example.com"],
+    headers={"X-Custom-Header": "value", "Reply-To": "reply@example.com"},
+)
+```
+
+#### How do I create a custom email backend?
+
+Subclass [`BaseEmailBackend`](./backends/base.py#BaseEmailBackend) and implement the `send_messages` method:
+
+```python
+from plain.email.backends.base import BaseEmailBackend
+
+class MyBackend(BaseEmailBackend):
+    def send_messages(self, email_messages):
+        # Your sending logic here
+        return len(email_messages)
+```
+
+## Installation
+
+Install the `plain.email` package from PyPI:
+
+```bash
+uv add plain.email
+```
+
+Add `plain.email` to your `INSTALLED_PACKAGES` and configure the required settings:
+
+```python
+# settings.py
+INSTALLED_PACKAGES = [
+    # ...
+    "plain.email",
+]
+
+EMAIL_BACKEND = "plain.email.backends.smtp.EmailBackend"
+EMAIL_DEFAULT_FROM = "noreply@example.com"
+
+# For SMTP (adjust for your mail provider)
+EMAIL_HOST = "smtp.example.com"
+EMAIL_PORT = 587
+EMAIL_HOST_USER = "your-username"
+EMAIL_HOST_PASSWORD = "your-password"
+EMAIL_USE_TLS = True
+```
+
+For local development, use the console backend to see emails in your terminal:
+
+```python
+EMAIL_BACKEND = "plain.email.backends.console.EmailBackend"
+```

plain_email-0.15.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+plain/email/CHANGELOG.md,sha256=5o266slsieqY_0Ci5-GeE93uTESuZU5xR63tpxyUb3o,3289
+plain/email/README.md,sha256=JRL1Q3S0KAnZSe2u7xp56kgLPq3zFUDeckYWOT9igr8,7024
+plain/email/__init__.py,sha256=_wQC03wth7dgSqKaFG3IGkdJN5yhXfDH7M7pLNYm7IQ,3391
+plain/email/default_settings.py,sha256=dZlKwsLBAJSZ8cRt117Db3qPf97xbPUaGEHbUmlv2CU,881
+plain/email/message.py,sha256=Wlb0qyxmIow3dWIvFEfDuj-G041x-L-aa7GU0YiSr64,23144
+plain/email/utils.py,sha256=b9DzVVvI6BRwIVWSud_sRRchanBztH1p6qCy5-g9-ns,610
+plain/email/backends/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+plain/email/backends/base.py,sha256=7XDlJv07IMSES10pduu_ayCaznD2kwIyo3iAHWg9uQs,2009
+plain/email/backends/console.py,sha256=M7xW13XMjrozwnkkfTv2RxkV0vKp20EvTpIQpIfCGek,1745
+plain/email/backends/filebased.py,sha256=mEqxazVXHihkndshgkD56qMoXww5CQpZOpsoPh0tQEw,2733
+plain/email/backends/smtp.py,sha256=IqpYXXsf1LTh1uqHR9_gGyYTHwuRdtdX2kUtaRQY01Q,6258
+plain_email-0.15.0.dist-info/METADATA,sha256=Voan-CdvnmoWHGxf7EW_vrl36ZGLXZcoBxT3IFCSpHM,7337
+plain_email-0.15.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+plain_email-0.15.0.dist-info/licenses/LICENSE,sha256=m0D5O7QoH9l5Vz_rrX_9r-C8d9UNr_ciK6Qwac7o6yo,3175
+plain_email-0.15.0.dist-info/RECORD,,

plain_email-0.13.0.dist-info/METADATA

@@ -1,34 +0,0 @@
-Metadata-Version: 2.4
-Name: plain.email
-Version: 0.13.0
-Summary: Everything you need to send email in Plain.
-Author-email: Dave Gaeddert <dave.gaeddert@dropseed.dev>
-License-Expression: BSD-3-Clause
-License-File: LICENSE
-Requires-Python: >=3.13
-Requires-Dist: plain<1.0.0
-Description-Content-Type: text/markdown
-
-# plain.email
-
-**Everything you need to send email in Plain.**
-
-- [Installation](#installation)
-
-## Installation
-
-Install the `plain.email` package from [PyPI](https://pypi.org/project/plain.email/):
-
-```bash
-uv add plain.email
-```
-
-Add `plain.email` to your `INSTALLED_PACKAGES`:
-
-```python
-# settings.py
-INSTALLED_PACKAGES = [
-    # ...
-    "plain.email",
-]
-```

plain_email-0.13.0.dist-info/RECORD

@@ -1,15 +0,0 @@
-plain/email/CHANGELOG.md,sha256=XwhhOVmTMUu0nPLCJTX9pPJtpV0p5SAmeJHnluXJ7b4,2379
-plain/email/README.md,sha256=F8R2Mu_U-jOEa2HVTzVpODGD-Ml6jbn9KYnJLl8p6lI,364
-plain/email/__init__.py,sha256=CceyW_Lf4OC6VIkPPvstwNT6Z-RtIkyym_k_s8HMw5E,3691
-plain/email/default_settings.py,sha256=B2V9UOq4MDG5VQM9VKTRiBqQ6ppUyoRFq9j7Qi9bO_M,811
-plain/email/message.py,sha256=hEpEEuw6K9z6zfAbG3nMujaJvaNNkmin51SWkA6iOgQ,23023
-plain/email/utils.py,sha256=1B12SBVCpbLVN5bSaewiEpcDdz-7KM2SpXPC33Dcef8,555
-plain/email/backends/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-plain/email/backends/base.py,sha256=7XDlJv07IMSES10pduu_ayCaznD2kwIyo3iAHWg9uQs,2009
-plain/email/backends/console.py,sha256=M7xW13XMjrozwnkkfTv2RxkV0vKp20EvTpIQpIfCGek,1745
-plain/email/backends/filebased.py,sha256=mEqxazVXHihkndshgkD56qMoXww5CQpZOpsoPh0tQEw,2733
-plain/email/backends/smtp.py,sha256=PmBO3EeYDZLjcBvTCSlWq0THYn4Nv2joGTS1-21Bft0,6253
-plain_email-0.13.0.dist-info/METADATA,sha256=KruBYNqIQ_6ndZ-dqNVYArq4KX61C6GCcYpkOqI9Hbk,677
-plain_email-0.13.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-plain_email-0.13.0.dist-info/licenses/LICENSE,sha256=m0D5O7QoH9l5Vz_rrX_9r-C8d9UNr_ciK6Qwac7o6yo,3175
-plain_email-0.13.0.dist-info/RECORD,,