Metadata-Version: 2.5
Name: epistrel
Version: 0.2.0
Summary: Mail utils
Requires-Python: >=3.12
Requires-Dist: cohaerum-config[yaml]>=0.2.0
Requires-Dist: cohaerum>=0.2.0
Requires-Dist: dkimpy>=1.1.8
Description-Content-Type: text/markdown

# Epistrel

Epistrel provides a typed sending interface, an SMTP provider, and a
command-line client. Configuration is loaded through `from cohaerum import
config`, using the callable configuration interface.

The SMTP provider supports text messages, attachments, CC/BCC, Reply-To,
SMTP authentication, verified TLS, and optional RSA DKIM signing. It does
not implement mailbox reading or SMTPUTF8.

## Installation

Install into a virtual environment.

```bash
python3 -m venv .venv
. .venv/bin/activate
python -m pip install -e '.'
```

The `cohaerum` and `cohaerum-config` dependencies must be available from your
configured package source or already installed in the environment. This
project does not configure or initialize Cohaerum itself.

The executable is named `epistrel`. Use `python -m epistrel` to run the CLI
without relying on the console script.

## Configuration

The configuration loader reads `epistrel.account.default` and
`epistrel.account.<account>`. The following example shows the logical
configuration tree; place it wherever your Cohaerum configuration exposes
these keys.

```yaml
epistrel:
  account:
    default: personal

    personal:
      sender: Example Sender <sender@example.org>
      server: smtp.example.org
      security: starttls
      port: 587
      timeout: 30

      username: sender@example.org
      password_env: SMTP_PASSWORD

      dkim:
        selector: "20220823"
        domain: example.org
        private_key: /etc/epistrel/dkim/20220823.pem
```

`password_env` names an environment variable containing the password.
Alternatively, configure `password` directly. The two options are mutually
exclusive, and authentication requires TLS.

The security modes are `starttls`, `ssl`, and `plain`. Their default ports are
587, 465, and 25 respectively. The default security mode is `starttls`.
Both TLS modes verify certificates and hostnames using the system trust store.
STARTTLS is required when selected; there is no unencrypted fallback.

For a trusted relay that accepts unauthenticated SMTP on port 25, configure
that explicitly:

```yaml
epistrel:
  account:
    default: relay

    relay:
      sender: Example Sender <sender@example.org>
      server: relay.example.org
      security: plain
      port: 25
```

Plain SMTP does not encrypt the connection between this client and the relay.

### Legacy DKIM configuration

The old selector-only form remains supported:

```yaml
dkim: "2459813"
```

Without an explicit `private_key`, the loader reads the key from the XDG
configuration directory:

```text
$XDG_CONFIG_HOME/epistrel/<selector>.pem
```

When `XDG_CONFIG_HOME` is unset, this is `~/.config/epistrel/<selector>.pem`.
A mapping with a selector but no private-key path uses the same fallback.
Explicit key paths are preferred for new configurations.

If no DKIM domain is configured, the provider uses the sender's mailbox domain.
The corresponding public key must be published in DNS. Configuring an unrelated
signing domain can break DMARC alignment.

Permission errors, invalid keys, and signing failures are reported rather than
silently disabling signing. The provider signs the serialized message once and
submits those bytes without reserializing them.

## Command-line usage

Each address argument must contain exactly one mailbox. Quote display names,
and repeat `--cc`, `--bcc`, or `--attach` for multiple values.

```bash
printf 'The deployment finished.\n' |
  epistrel -s 'Deployment report' recipient@example.org
```

An explicit body avoids reading stdin:

```bash
epistrel \
  --account personal \
  --subject 'Status' \
  --body 'Everything is running.' \
  recipient@example.org
```

Attachments, copies, and Reply-To can be supplied independently:

```bash
epistrel \
  --subject 'Report' \
  --body-file report.txt \
  --attach report.pdf \
  --attach metrics.csv \
  --cc 'Example Reviewer <reviewer@example.org>' \
  --bcc archive@example.org \
  --reply-to support@example.org \
  recipient@example.org
```

Use `--bcc-self` to send a hidden copy to the configured sender. Unlike the
old implementation, this is not enabled automatically.

To inspect the generated message without opening an SMTP connection:

```bash
epistrel \
  --subject 'Preview' \
  --body 'Example message.' \
  --dry-run \
  recipient@example.org > preview.eml
```

Dry runs still load configuration, read attachments, and perform configured DKIM
signing. BCC recipients are not written to the preview because they belong only
to the SMTP envelope.

Body files and stdin must contain UTF-8 text. Without `--body` or `--body-file`,
the CLI reads stdin until EOF; in a terminal, finish input with Ctrl-D.

### Exit statuses

Successful submission returns status 0. Runtime errors return 1, argument
errors return 2, partial recipient refusal returns 3, and interruption returns
130.

A partial refusal means the server accepted the message for some recipients
but rejected others. Do not blindly resend the original message to everyone,
because accepted recipients may receive duplicates.

SMTP acceptance is not proof of final delivery. Network failure around the
end of SMTP DATA can also leave the submission outcome uncertain. The provider
does not automatically retry.

## Python usage

Application code can depend on `MailSender` rather than the concrete SMTP
implementation. Configuration loading is optional: callers may construct
`SMTPSettings` directly.

```python
from epistrel import (
    Attachment,
    MailSender,
    OutgoingMessage,
    SMTPProvider,
    SendResult,
    load_smtp_settings,
)


def send_report(sender: MailSender) -> SendResult:
    return sender.send(
        OutgoingMessage(
            to=("recipient@example.org",),
            subject="Report",
            body="The report is attached.",
            attachments=(
                Attachment.from_path("report.pdf"),
            ),
        )
    )


provider = SMTPProvider(load_smtp_settings("personal"))
result = send_report(provider)

if not result.complete:
    for recipient, refusal in result.refused.items():
        print(recipient, refusal.code, refusal.message)
```

An alternative sending provider only needs a compatible `send()` method.
Explicit inheritance from `MailSender` is not required.

Mailbox reading should use a separate protocol when introduced. Listing
messages, fetching bodies, changing flags, and managing folders are not
responsibilities of a sending provider.

## Limitations and tests

Attachments and complete messages are held in memory. This implementation is
intended for ordinary email sizes, not streaming very large attachments.

Unicode display names, subjects, bodies, and filenames are supported.
Mailbox addresses themselves must be ASCII; SMTPUTF8 negotiation is not
implemented. For internationalized domains, supply the ASCII domain form.

The sender address is fixed by the selected account and is used for both
the From header and SMTP envelope sender. Separate bounce addresses and HTML
alternatives are not currently implemented.

Run the tests after installing the package:

```bash
python -m unittest discover -s tests -v
```

The tests cover message construction, BCC privacy, validation, partial
recipient refusal, DKIM key discovery, and SMTP connection cleanup using a
mocked transport. They do not replace integration tests against your SMTP
server or DNS-backed DKIM verification.
