btx_lib_mail

Send email from Python and from the shell.

Most mail libraries are sold on a feature list, and nobody loses sleep over a feature list. What keeps you up is the one message that matters failing at the worst possible time: the 2 GB export that runs your server out of memory, the customer whose name comes through as garbled bytes, the primary relay that drops mid-send. btx_lib_mail is built for that message, not for the demo.

What you get:

• Send a 100 GB attachment on a box with almost no free memory. The message is streamed to disk and pushed to the server one chunk at a time, so peak memory stays flat whether the file is 100 kB or 100 GB. It never holds the whole payload in RAM, because the RAM you do not have is the RAM that kills the job. (Attachments are capped at 25 MiB by default; raise attachment_max_size_bytes for the big ones. The trade is scratch disk of about 1.37x the attachment, once, however many recipients.)
• BDAT when the server supports it, DATA when it does not. If the far end advertises CHUNKING (RFC 3030) the message goes out in length-prefixed chunks; otherwise it falls back to a correct, dot-stuffed DATA phase. You do not pick, the library negotiates.
• Subjects and bodies that encode correctly. Umlauts, emoji, CJK, a subject that is only a full stop: all handled by the standard library's modern email machinery, not by a regex someone wrote at 2am. No more Grüße arriving as Grüße in a customer's name.
• Internationalised addresses (RFC 6531 SMTPUTF8). empfänger@müller.de works as sender or recipient, NFC-normalised, and is sent as UTF-8 to relays that offer SMTPUTF8; ASCII mail is unchanged.
• No more hand-rolling smtplib. No MIME assembly, no dot-stuffing, no failover loop. One function call, or one command.
• A command-line mailer. btx-lib-mail send ... turns any shell into a mail client, with the same streaming and the same checks.
• Attachments checked before they leave. Path traversal, symlinks, /.ssh/, system directories, dangerous extensions (Windows and Unix executables alike) and a size cap are refused by default, so you do not email your private key by accident. Each file is opened once, right after its checks, and the bytes sent are the bytes of the file that was checked.
• One error type to catch. Every refusal by the library and every delivery failure is a BtxMailError, and the CLI has --json output and documented exit codes for scripts and agents.

The part that costs us and earns your trust is the unglamorous part: every wire path is proven end to end against a real SMTP server, including BDAT, STARTTLS with authentication, and a memory bound that does not grow with the attachment. That confidence is the actual product. Go and try the daft thing: point it at a spare mailbox and attach something absurd.

Quickstart

Install with uv, with a cooldown that skips releases younger than 7 days (why):

# install uv first, if you do not have it (macOS / Linux)
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

uv tool install --exclude-newer "7 days" btx_lib_mail    # the CLI on your PATH

To use the library in a project, add [tool.uv] exclude-newer = "7 days" to its pyproject.toml, then uv add btx_lib_mail. Plain pip install btx_lib_mail works too, without the cooldown.

Send an email from Python:

from btx_lib_mail import send

send(
    mail_from="alerts@example.com",
    mail_recipients=["oncall@example.com"],
    mail_subject="build failed",
    mail_body="See CI logs for details.",
    smtphosts=["smtp.example.com:587"],
    credentials=("mailer", "DUMMY-PLANTED-password"),
)

Send to an internationalised address (the relay must offer SMTPUTF8):

send(mail_from="alerts@example.com", mail_recipients=["empfänger@müller.de"], mail_subject="Grüße", mail_body="Hallo.", smtphosts=["smtp.example.com:587"])

Attach a huge file without running out of memory (streamed, never buffered whole):

from pathlib import Path
from btx_lib_mail import send

send(
    mail_from="backups@example.com",
    mail_recipients=["archive@example.com"],
    mail_subject="nightly dump",
    mail_body="Attached.",
    smtphosts=["smtp.example.com:587"],
    attachment_file_paths=[Path("/data/nightly-dump.tar")],
    attachment_max_size_bytes=50 * 1024**3,  # the default cap is 25 MiB; raise it for big files
)

Send from the shell:

btx-lib-mail send \
  --host smtp.example.com:587 \
  --sender alerts@example.com \
  --recipient oncall@example.com \
  --subject "Ping" \
  --body "Smoke test"

Both commands (btx_lib_mail and btx-lib-mail) and python -m btx_lib_mail run the same CLI.

smtp_password is a SecretStr (masked in repr() and logs); see Configuration - Credentials for non-ASCII passwords, numeric passwords from environment layers, and what to keep out of a custom validator's error message.

Use send(config=...) instead of the global conf when an application holds its own settings object (a worker with per-tenant credentials, a test that must not touch global state):

from btx_lib_mail import ConfMail, send

tenant_config = ConfMail(
    smtphosts=["smtp.example.com:587"],
    smtp_username="mailer",
    smtp_password="DUMMY-PLANTED-password",
)
send(
    mail_from="alerts@example.com",
    mail_recipients=["oncall@example.com"],
    mail_subject="build failed",
    mail_body="See CI logs for details.",
    config=tenant_config,  # every value not also passed explicitly comes from here, not conf
)

ConfMail refuses a name it does not have, and its field names are not the send() keyword names: ConfMail(use_starttls=False) raises ConfigurationError (a pydantic ValidationError); the field is smtp_use_starttls.

Use it from an AI agent (zero install)

btx_lib_mail is built to be driven by LLMs and agents, not only by people. An agent can send mail with nothing installed, straight from PyPI via uvx (the cooldown skips releases younger than 7 days):

uvx --exclude-newer "7 days" btx-lib-mail send \
  --host smtp.example.com:587 \
  --sender alerts@example.com --recipient oncall@example.com \
  --subject "Ping" --body "Smoke test"

The library also ships a Claude Code skill (python-send-mail) that teaches an agent when and how to use it: install, uvx, the library API, testing through the Transport seam, the CLI (--json, --env-file, --password-file), streaming and BDAT, and attachment security. Install it into any project:

/plugin marketplace add bitranox/btx_lib_mail
/plugin install btx_lib_mail

It is also available in the central bitranox-skills marketplace as coding-python-send-mail.

Architecture

The package is layered, and make test enforces it with one import-linter layers contract ([tool.importlinter] in pyproject.toml): a module imports only from the layers below its own, and the modules sharing a layer do not import each other.

Module reference describes each module.

Documentation

• Installation - pip, pipx, uv, source builds; Python 3.10+ baseline
• Command-line interface - all CLI commands and send options
• Configuration - ConfMail, precedence, and BTX_MAIL_* environment variables
• Streaming and BDAT - how bounded-memory delivery and RFC 3030 CHUNKING work
• Attachment security - the checks applied before an attachment is sent
• Public API reference - send, ConfMail, the exceptions, the Transport seam, and exported constants
• Module reference - internal design and delivery path

Project docs

• Install Guide
• Development Handbook
• Contributor Guide
• Changelog
• AI Transparency
• Our Stance on AI
• License