update-email-templates

---
name: update-email-templates
description: Update Authgear email templates using the correct source files, translation files, and commit order. Use when editing email wording, email structure, or subject lines.
---

# Update Email Templates

Follow this workflow whenever updating email templates.

## Scope Rules

1. Only edit source template files:
   - `resources/authgear/templates/en/messages/*.txt.gotemplate`
   - `resources/authgear/templates/en/messages/*.mjml.gotemplate`
2. Do not edit generated template files directly:
   - `resources/authgear/templates/en/messages/*.txt`
   - `resources/authgear/templates/en/messages/*.mjml`
3. In `*.txt.gotemplate` and `*.mjml.gotemplate`, use translations from:
   - `resources/authgear/templates/en/messages/translation.json`
4. Always edit English templates only at source stage.
   - Do not manually update non-`en` locales in source-edit commits.
5. Email subject translations are defined in:
   - `resources/authgear/templates/en/translation.json`

## Workflow

1. Edit source templates first:
   - `resources/authgear/templates/en/messages/*.txt.gotemplate`
   - `resources/authgear/templates/en/messages/*.mjml.gotemplate`
   - `resources/authgear/templates/en/messages/translation.json` (body/content translations)
   - `resources/authgear/templates/en/translation.json` (subject translations)
2. Generate `.mjml` from `.mjml.gotemplate`:
   - `go run ./scripts/generatemjml/main.go -i resources/authgear/templates`
3. Commit source edits and generated `.mjml` in one commit.
4. Before regenerating non-English translations, delete the changed keys from all non-`en` locale files so the generator knows to recreate them:
   - For `en/messages/translation.json` changes, delete the **top-level key** (e.g. `UsageAlert`, not `UsageAlert.Alert.Title`) from all non-`en` `messages/translation.json` files:
     - `make templates-translation-json-del-key KEY=<TopLevelKey>`
   - For `en/translation.json` subject changes, delete the changed key from all non-`en` `translation.json` files:
     - `make translation-json-del-key KEY=<key>`
   - Run once per changed top-level key.
5. In a separate commit, generate non-English translations:
   - `make -C scripts/python generate-translations`
   - Requires being logged in to Claude: `claude login`
   - If not logged in, stop and ask the user to run `claude login` first.
6. Finally, generate HTML emails:
   - `make html-email`

## Commit Boundaries (Required)

- Commit 1:
  - Source edits (`*.gotemplate`, `en/messages/translation.json`, optional `en/translation.json`)
  - Generated `.mjml`
- Commit 2:
  - Generated non-English translations (`make -C scripts/python generate-translations`)
- Commit 3:
  - Generated email HTML artifacts (`make html-email`)

Do not combine generated artifacts (`.html`, `.txt`, non-`en` translations) in the same commit as source `*.gotemplate` edits.

More agent context in authgear/authgear-server

20 other files this repository gives its agents.