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

  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.2.1

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.2.1
File Size Uploaded Provenance Actions
cde_mailer-0.2.1.tar.gz 39.6 kB Without provenance Details for cde_mailer-0.2.1.tar.gz

Built distribution (wheel)

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

Total release size: 64.3 kB

Release files / cde_mailer-0.2.1.tar.gz

Download URL cde_mailer-0.2.1.tar.gz
Size 39.6 kB
Tags Source
SHA-256 checksum
How to use checksums
6262ab3af7567e650d3fd16de0843a94d9cdefc78ec498715f8a53bf9d0b2cb7
BLAKE2b-256 checksum
How to use checksums
c9d5d6ee63c00aa3b07ee7ba8a3a8e0f0e6516b74c092219b11b67d02c397f2f
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.1-py3-none-any.whl

Download URL cde_mailer-0.2.1-py3-none-any.whl
Size 24.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
f33301cb63d6bb9da9d782ac85c621a473fbeb9a6d5abc089e556ae92458adfb
BLAKE2b-256 checksum
How to use checksums
08936ca4b10e4d79074874faed7fa90d0e108127f57aba9594df5ffaf733c37a
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.1

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