Template management specification

Purpose and boundaries

The replacement CRM must let authorised staff manage reusable operational email templates without editing workflow logic or source code. Templates own content and sender configuration. Workflows own triggers, timing, recipients, stage changes, tasks, and manual overrides.

In scope

• Weddings and Events operational one-to-one and workflow email.
• HTML and plain-text content, approved Microsoft Graph sender identities, and allowlisted merge fields.
• Draft, review, test, publish, disable, retire, rollback, usage visibility, audit, delivery outcomes, and migration of confirmed HubSpot content.

Out of scope for first release

• Bulk marketing campaigns, segmentation, subscription management, and marketplace integrations.
• Workflow trigger editing from the template screen, arbitrary scripts, unsafe custom HTML, and automatic AI rewriting or publishing.

Design principles

1. Published versions are immutable and every workflow action references a specific version.
2. No production send occurs without a resolved recipient, approved sender, and rendered content.
3. A template edit cannot silently change a live workflow.
4. All material changes are attributable, timestamped, auditable, and reversible.
5. Raw imported source content is retained separately from transformed content.

Required capabilities

• List templates by name, purpose, pipeline, workflow, status, owner, and last updated date.
• Create a template with name, subject, body, sender identity, purpose, and permitted recipient context.
• Amend a template by creating a new version. Published versions are never overwritten in place.
• Preview rendered emails with representative contact and deal data.
• Validate merge fields, missing values, unsupported fields, links, and sender permissions before publishing.
• Send a controlled test email to an authorised internal recipient.
• Submit a version for review, then publish only after authorised approval.
• Disable or retire templates without deleting their history.
• Roll back a workflow to the previous published template version.
• Show every workflow, pipeline, trigger, and action using a template.
• Keep an audit trail for create, edit, test, submit, approve, publish, disable, and rollback events.

Version and publishing rules

1. Drafts are editable by authorised template managers.
2. A published version is immutable.
3. Editing a published template creates a new draft version.
4. Only one version may be active for a workflow action at a time.
5. A referenced template cannot be disabled without an explicit replacement or pause decision.
6. Every published version records its approver, publication time, sender, subject, body, merge fields, and workflow references.

Permissions

Users may not approve their own changes under normal permissions. Test sends are restricted to approved internal recipients, and sender identities are separately permissioned.

Lifecycle

Content and merge fields

Each version stores name, purpose, pipeline, owner, subject, HTML body, plain-text body, sender, reply-to, preview text, merge-field manifest, checksum, source reference, and publication metadata.

First-release merge fields are limited to contact first and last name, email address, deal name, pipeline, stage, owner name, close date, quote expiry date, approved organisation name, current New Zealand date, template name, and workflow name.

Authoring, preview, and test send

• The catalog supports search, filters, version comparison, usage visibility, and lifecycle actions.
• The editor separates subject, HTML, plain text, sender, reply-to, preview text, purpose, and merge fields.
• Preview supports sample data, an authorised contact/deal, and an explicit missing-data view.
• Test sends show recipient, sender, subject, body, version, and source record before sending.
• Test sends go only to the initiating user or an approved internal recipient and never trigger workflow side effects.

Workflow linkage

Each workflow email action references a template version, sender identity, recipient rule, timing and timezone, missing-data policy, and failure policy. The workflow view shows the binding and the template screen shows every workflow using it.

Sending uses Microsoft Graph. The service validates recipient, consent, suppression, sender permissions, and required fields; renders HTML and plain text; records an idempotency key; retries bounded transient failures; and routes permanent failures to an operator-visible exception queue.

Minimum data model

The first release requires records for email_template, email_template_version, workflow_template_binding, template_test_send, email_delivery, and template_audit_event.

These records must retain immutable content checksums, lifecycle state, actor, timestamps, source references, workflow bindings, sender identity, recipient rule, provider message ID, idempotency key, delivery outcome, and safe error details.

Security and operations

• Sanitise HTML and reject scripts, event handlers, unsafe URLs, and unapproved tracking content.
• Keep secrets out of templates and logs. Restrict previews and test sends to authorised users.
• Monitor publish, rollback, send failure, retry exhaustion, and sender changes.
• Back up templates, bindings, audit events, and delivery records and include them in restore tests.

Delivery sequence

1. Approve this specification, role matrix, and Microsoft Graph sender boundaries.
2. Add template entities and audit migrations.
3. Build catalog, authoring, rendering, test-send, approval, binding, and Graph services.
4. Import the Final Email fixture as a draft and confirm mapping, recipient, timing, and sender.
5. Run acceptance tests, migration rehearsal, controlled test send, rollback test, and cutover evidence.

Acceptance tests

• An authorised template manager can create a draft without changing a live workflow.
• A published version cannot be edited in place.
• Preview identifies unknown merge fields and missing required values before publishing.
• A test email records recipient, sender, template version, and timestamp.
• Publishing a new version updates the linked workflow only after approval.
• Rollback restores the previous version and records who performed it and why.
• A retired or unlinked template remains searchable in the audit history.
• Duplicate workflow execution does not create duplicate outbound messages.
• Transient Microsoft Graph failure retries within limits; permanent failure appears in the exception queue.
• Unsafe HTML is rejected or sanitised and all lifecycle events appear in the audit history.
• Backup and restore preserve published versions, bindings, audit events, and delivery records.

Approval required from Oliver Ormond as project approver and product owner. Technical owner: Stuart Gordon.