Skip to main content

cde-mailer

cde-mailer is a template-based email dispatch and mail-merge tool developed for CdE e.V. (Club der Ehemaligen der Deutschen SchülerAkademien e.V.). It renders personalized emails from .cdemail job files and semicolon-delimited CSV exports using Jinja2, generates local HTML previews for mandatory proof-reading, and dispatches messages reliably through Zammad with built-in ticket deduplication.


Key Features

  • Jinja2 Mail-Merge: Render subjects, recipients (To, CC, BCC), tags, attachment paths, metadata, and bodies from CdE CSV exports (; delimiter, automatic persona.forename $\rightarrow$ persona_forename variable aliasing).
  • Two-Stage Safety Workflow: Automatically generates HTML previews in email_previews/ and pauses on first run (or whenever templates/data change) so you can proof-read before any network action occurs.
  • Pre-Dispatch Verification Dry-Run: Queries Zammad before sending to report the exact number of new tickets, appended articles, and ticket state changes that will occur.
  • Smart Zammad Deduplication: Uses Elasticsearch queries on customer address, group, tags, and article subject to prevent duplicate sends (skipifexists=true) and thread follow-up emails into existing tickets.
  • Open-Ticket Protection: Refuses to automatically close existing tickets that are currently open (e.g., when a participant has replied).
  • Audit Logging: Records every dispatched message with timestamp, recipient, subject, status, and Zammad ticket/article ID in sent_emails.log.csv.

Workflow Overview

flowchart LR
    A[".cdemail + .csv"] --> B["EmailJob Parser\n& Validator"]
    B --> C{"Previews\nChanged?"}
    C -- "Yes (1st Run)" --> D["Write HTML Previews\n(email_previews/) & Exit"]
    C -- "No (2nd Run)" --> E["Zammad Dry-Run\n& Statistics"]
    E --> F{"Confirm\n(y/N)?"}
    F -- "Yes" --> G["Dispatch via Zammad API\n& Log to sent_emails.log.csv"]

Installation

git clone https://tracker.cde-ev.de/orgas/cde-mailer.git
cd cde-mailer
uv sync

Using pip

pip install .

Quickstart

1. Create a Configuration File (config.toml)

Copy config.toml.example to config.toml and configure your Zammad group and API token:

backend = "zammad"
host = "tickets.cde-ev.de"
token_file = "zammad_token.txt"
zammad_group = "PfingstAkademie 2026"

(Tip: cde-mailer also supports embedding these settings under a [cde-mailer] table inside a shared config.toml.)

2. Author an Email Job (welcome.cdemail)

Create a .cdemail file with a header and body separated by ---:

Subject=Welcome to the academy, {{ persona_forename }}!
To={{ persona_username }}
CSV=participants.csv
Attachments= handbooks/handbook.pdf
Tags=pa2026, welcome
state=closed
skipifexists=true
---
Hello {{ persona_forename }},

We are delighted to welcome you to the academy!
Please find the participant handbook attached.

Best regards,
Your Orga Team

3. Generate Previews & Dispatch

  1. First run — generate HTML previews:
    uv run cde-mailer welcome.cdemail
    
    Inspect the generated files in email_previews/welcome/email_*.html.
  2. Second run — dry-run check & interactive dispatch:
    uv run cde-mailer welcome.cdemail
    
    Review the dry-run summary of new tickets/articles and confirm with y to send.

CLI Options Summary

cde-mailer [options] <job_files>...
Option Description
job_files One or more paths to .cdemail job files.
--config <path> Path to TOML configuration file (default: config.toml).
--host <host> Zammad host (overrides config).
--group <group> Zammad group for tickets (overrides config).
--token <token> Zammad API token string (overrides config).
--token_file <path> Path to Zammad API token file (overrides config).
--backend {zammad} Dispatch backend to use (default: zammad).
--dry-run Simulation mode: run Zammad verification checks without sending emails.
--non-interactive Skip preview-change pause and confirmation prompts.
-v, --verbose Increase logging verbosity (-v for INFO, -vv for DEBUG).

Python API Usage

cde-mailer can also be used as a typed Python library:

import pathlib
from cde_mailer import EmailJob, get_sender, process_email_job_files

# High-level orchestration
config = {
    "backend": "zammad",
    "host": "tickets.cde-ev.de",
    "token_file": "zammad_token.txt",
    "zammad_group": "PfingstAkademie 2026",
}
process_email_job_files([pathlib.Path("welcome.cdemail")], config)

# Or granular message inspection
job = EmailJob.load(pathlib.Path("welcome.cdemail"))
for message in job:
    print(message.to, message.subject)

Documentation & Contributing

Full documentation is available in the docs/ directory:

Want to contribute or add a new backend? See CONTRIBUTING.md.

License

Licensed under the Apache License, Version 2.0.

Metadata

Release files for cde-mailer 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for cde-mailer 0.1.0
File Size Uploaded Provenance Actions
cde_mailer-0.1.0.tar.gz 39.1 kB Without provenance Details for cde_mailer-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for cde-mailer 0.1.0
File Interpreter ABI Platform Actions
cde_mailer-0.1.0-py3-none-any.whl Python 3 none any Details for cde_mailer-0.1.0-py3-none-any.whl

Total release size: 63.9 kB

Release files / cde_mailer-0.1.0.tar.gz

Download URL cde_mailer-0.1.0.tar.gz
Size 39.1 kB
Tags Source
SHA-256 checksum
How to use checksums
071a71086b4381bb515c076fa20486a92965c3d839a45e90fb62496a3020c2c9
BLAKE2b-256 checksum
How to use checksums
863e7f5d4e03c6169b6b79acd60b6b56ef71870dd49b1969962bf395cb9f8a08
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.5

Release files / cde_mailer-0.1.0-py3-none-any.whl

Download URL cde_mailer-0.1.0-py3-none-any.whl
Size 24.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
c083773a100beb4b48deb4126f31afafc51b09a60b1b6315197185eb76a3d3f4
BLAKE2b-256 checksum
How to use checksums
bcd055b561812d555051824efe30db46914ea22fcacfbb2ec9fa6b0dfb0876eb
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.5

Security for cde-mailer 0.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page