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.
• 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.
• 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 and a size cap are refused by default, so you do not email your private key by accident.

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 a 100 GB attachment cannot breach. That confidence is the actual product. Go and try the daft thing: point it at a spare mailbox and attach something absurd.

Quickstart

Install:

pip install btx_lib_mail

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"),
)

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")],  # gigabytes are fine
)

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
)

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:

uvx 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, the CLI, 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.

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, functions, 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