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, automaticpersona.forename$\rightarrow$persona_forenamevariable 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
Using uv (Recommended)
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 in .eml format with headers and body separated by an empty line:
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
- First run — generate HTML previews:
uv run cde-mailer welcome.cdemail
Inspect the generated files inemail_previews/welcome/email_*.html. - Second run — dry-run check & interactive dispatch:
uv run cde-mailer welcome.cdemail
Review the dry-run summary of new tickets/articles and confirm withyto 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:
- Documentation Overview
- CLI Usage & Dispatch Workflow
- Configuration & Authentication
- Email Job Files (
.cdemail) & Templating - Zammad Backend & Deduplication Internals
- Architecture & Internals
- Python API Reference
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.2.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| cde_mailer-0.2.0.tar.gz | 39.4 kB | Without provenance | Details for cde_mailer-0.2.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| cde_mailer-0.2.0-py3-none-any.whl | Python 3 | none | any | Details for cde_mailer-0.2.0-py3-none-any.whl |
Total release size: 64.2 kB
Release files / cde_mailer-0.2.0.tar.gz
| Download URL | cde_mailer-0.2.0.tar.gz |
|---|---|
| Size | 39.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
65323c716ebd4683c608d14a336947bcc9077ac81b11f7191d4f1c26295302c6
|
|
BLAKE2b-256 checksum How to use checksums |
452d84ebe7d395a887d3ed3e4b5c255948c9147eb371e8eea2935c0372af0578
|
| 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.2.0-py3-none-any.whl
| Download URL | cde_mailer-0.2.0-py3-none-any.whl |
|---|---|
| Size | 24.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
11c00ac07910f55ad391665997e976522de5adf16f9597a5fcd1b97199f0f3dd
|
|
BLAKE2b-256 checksum How to use checksums |
f830e29f9eaa9fc028f167ed7d9cf3a77f42a78fc60da5b460e7518e17ef8d4f
|
| 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.2.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.