imio.emailkit

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:

Quickstart	install, then send your first styled mail
Architecture	the build-time / runtime seam, and why
Email builder	recipients, attachments, per-language sending
Authoring rules	eight ways a template breaks with a green build
Shipping templates	get your own add-on's templates discovered
Migrating a mail	you already build HTML bodies
Overrides & theming	three levels, plus a full opt-out

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. Two files describe why, and they are the authority when the three disagree:

• SPEC.md — goals, non-goals, architecture, phasing, and what was explicitly rejected.
• docs/DECISIONS.md — the decision record: every measured finding, every reverted attempt, every "this looked like it worked".

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.