Agent Mail: templated SMTP for bots and automation

DarDev Agent Mail is a small Python package and CLI for sending branded notification email from bot@agents.dardev.net through Stalwart on mta.dardev.net. It targets ops scripts, CI jobs, and Cursor agents that need a reliable SMTP path without Listmonk campaigns, Zoho credentials, or hand-built MIME. Stdlib only—no pip dependencies beyond editable install of packages/agent-mail.

Agent Mail is not human webmail. It complements send.dardev.net product mail and sales.dardev.net outreach by isolating programmatic volume on agents.dardev.net—the three-outbound-domains-send-sales-agents guide maps all three Stalwart identities on one MTA.

When to use Agent Mail

• Deploy finished notifications to you@example.com or staff distribution lists
• Scraper or import completion summaries with action links to ops.dardev.net
• CI pipeline alerts from GitHub Actions or local Fabric tasks
• Agent runner status after long-running platform-bus jobs
• Low-volume operational pings that should never touch Listmonk TX templates

Use Listmonk when you need subscription management, open tracking, or marketing list compliance. Use Agent Mail when a bot or script sends a one-off templated notice to a known address. Use Zoho only for @dardev.net human 1:1 mail—not for automation SMTP.

Setup and environment

Install editable from repo root: pip install -e packages/agent-mail. Load credentials from ops/.env.local automatically when running from the monorepo—never commit passwords to git or news article drafts.

• AGENTS_SMTP_HOST — mta.dardev.net externally; stalwart hostname inside Docker on dardev-vps
• AGENTS_SMTP_PORT — 465 or 587 inferred from AGENTS_SMTP_TLS
• AGENTS_SMTP_TLS — ssl or starttls
• AGENTS_SMTP_USER — bot@agents.dardev.net default
• AGENTS_BOT_PASSWORD — required service account password set in vault or local env only
• AGENTS_FROM_NAME — DarDev Agent default display name
• AGENTS_TEMPLATE_DIR — override package templates/ for custom layouts
• AGENTS_BRANDING — 1 enables logo; 0 disables
• AGENTS_LOGO_MODE — cid inline attachment, url HTTPS img, or off

CLI usage

List built-in templates: python -m agent_mail templates. Dry-run render without SMTP: python -m agent_mail render -t notification -v title="Deploy finished" -v summary="Staging is live." Send templated mail: python -m agent_mail send --to you@example.com -t notification -v title="Agent task done" -v summary="Import completed with 0 errors." -v action_url="https://ops.dardev.net" -v action_label="Open Ops".

Raw send without template: python -m agent_mail send-raw --to you@example.com --subject "Ping" --text "Hello from agent mail." Repo wrapper scripts/agents/send-mail.py accepts the same flags for operators who prefer a single entry script.

SDK integration

Python apps import AgentMailRunner.from_env() and call run(recipient, template_name, variables). Low-level AgentMailClient.from_env() exposes send() for plain subject and body when templates are overkill.

from agent_mail import AgentMailRunner

runner = AgentMailRunner.from_env()
result = runner.run(
    "you@example.com",
    "notification",
    {
        "agent_name": "Ops Scraper",
        "title": "Scrape complete",
        "summary": "1,204 schools staged.",
        "action_url": "https://ops.dardev.net",
    },
)
print(result)

On dardev-vps Docker apps, set AGENTS_SMTP_HOST=stalwart and port 465 on the internal Compose network. External developers tunnel or use mta.dardev.net with TLS like any SMTP client.

Templates and branding

Built-in notification template ships as templates/notification.meta.json, .txt, and .html siblings. Variables: agent_name, title, summary, action_url, action_label optional, plus brand_header, product_name, support_url, year from meta defaults.

Every send includes DarDev logo by default. cid mode embeds agent_mail/assets/dardev-logo.png as inline attachment—works offline. url mode references https://news.dardev.net/assets/media/dardev-logo-email.png. Templates expose {{brand_header}} and {{brand_text_header}}; raw sends auto-wrap with the same branding.

Add a template by copying the three-file pattern, setting subject in .meta.json, and using {{var}} placeholders. Keep HTML simple for mail client compatibility—tables for layout, inline styles, no external CSS bundles.

Deliverability and identity

Outbound mail authenticates as agents.dardev.net: SPF, DKIM, and DMARC records on GoDaddy per subdomain bootstrap. PTR for the VPS IP remains mta.dardev.net. Because bot volume is isolated, a misconfigured script spikes agents reputation—not send.dardev.net warmup curves used for newsletters.

The inside-unified-mailer-stack guide shows how Stalwart, Listmonk, and bus jobs connect. Agent Mail is a thin SMTP client on the agents channel—no CRM timeline writes, no Listmonk subscriber rows unless you separately integrate those systems.

Observability and failure handling

AgentMailRunner.run returns a structured result object suitable for logging in Fabric tasks or CI steps—capture success, SMTP response codes, and template name in your job output. When SMTP auth fails, verify AGENTS_SMTP_HOST resolves to stalwart on VPS internal networks and that the bot account password was rotated in Stalwart WebAdmin without stale env on the runner host.

Rate limits follow Stalwart per-account policy, not Listmonk campaign throttles. Keep notification batches small; queue heavy human mail through send.dardev.net paths documented in hybrid-sender-listmonk-stalwart-complete. Retry transient 4xx with exponential backoff in caller code—the SDK does not auto-retry to avoid duplicate alert storms.

App integration checklist

1. pip install -e packages/agent-mail or add to PYTHONPATH in app venv
2. Set env vars or pass AgentMailConfig explicitly in tests
3. Use notification template for structured alerts; send-raw for debug only
4. Point action_url at Ops or CRM deep links recipients can act on
5. Keep recipient lists small—Agent Mail is not bulk SMTP