Transactional email templating for the iMio Plone ecosystem. Author HTML mails with a modern toolchain — Maizzle 6 (Vue SFC + Tailwind CSS 4) — and render them at runtime with Chameleon, so that no Node.js ever runs in production.

Installing it restyles Plone's stock password-reset, registration and username-reminder mails immediately. That is the point: the mails a citizen actually receives from a commune are the ones nobody ever gets round to designing.

📖 Documentation

https://imio.github.io/imio.emailkit/

Everything is there: the quickstart, the architecture, the full API reference, the template-authoring rules, how to ship templates from your own add-on, and how to override what this package ships.

Some entry points worth naming:

Installation

pip install imio.emailkit

Then install the add-on in Site Setup, or apply the imio.emailkit:default GenericSetup profile — which restyles Plone's own transactional mails. Use imio.emailkit:base for the runtime only.

[!IMPORTANT] Behind a reverse proxy, declare trusted-proxy in zope.conf, or the login-help mails will name the proxy's own IP address instead of the client's. Why, and why the header is not read directly: Installation & profiles.

from imio.emailkit import Email

Email("imio.emailkit:notification").to(member).with_context(
    title=title, intro=intro, cta_url=url
).send()

Compatibility

Plone 6.0, 6.1 and 6.2 on Python 3.10 to 3.13.

[!IMPORTANT] Classic UI only, and deliberately so. These are emails: there is no Volto component and no REST endpoint to write. Rendering is isolated in imio.emailkit.render, which has no dependency on the request.

[!NOTE] Building templates needs Node.js 22+. Installing, testing and running the add-on never does — that is the whole architecture. If you only consume the mails it ships, you will never install Node.

Contribute

• Issue tracker
• Source code
• Contributing guide

Prerequisites ✅

• An operating system that runs all the requirements mentioned.
• uv
• Make
• Git
• Node.js 22+ — only to build email templates

Installation 🔧

1. Clone this repository, then change your working directory.

   git clone git@github.com:IMIO/imio.emailkit.git
   cd imio.emailkit
   

2. Install this code base.

   make install
   

Run make help for every target. The ones you will reach for most: make test, make check (format then lint), make start, make create-site, make build-emails, make check-emails, make preview-emails.

The design record

This README and the documentation site describe what the package does. docs/DECISIONS.md describes why, and it is the authority when the two disagree: every measured finding, every reverted attempt, every "this looked like it worked".

Comments throughout the code cite a SPEC.md by section number (§4, §6.2, §7). That file is no longer in the repository; the citations are kept as stable names for the contracts they refer to, and DECISIONS.md is where the reasoning behind each one actually lives.

SKILL.md carries the authoring conventions for AI-assisted work, which is how much of the template work here is done.

The documentation site itself lives in docs/site/ — see its README for how to add a page.

License

The project is licensed under GPLv2.