fix: brand outbound email templates with ZapDesk + KnowAll AI logos by akash2017sky · Pull Request #378 · knowall-ai/zapdesk

akash2017sky · 2026-05-09T15:18:21Z

Summary

All four outbound email templates (ticketConfirmationTemplate, agentReplyTemplate, statusChangeTemplate, sendTestEmail) now share a single branded layout: ZapDesk logo at the top, KnowAll AI logo + link in the footer, and a refined CTA button that reads consistently across Gmail web, Outlook desktop, Outlook web and Apple Mail.

New public/email/ folder hosts the PNG assets, referenced by absolute URL so any email client can fetch them.
ZapDesk logo PNG is generated from the existing public/assets/logo.svg via sharp (script: scripts/generate-email-assets.mjs) — single source of truth, regeneratable.
Logo URLs are env-overridable (ZAPDESK_LOGO_URL, KNOWALL_LOGO_URL) for deployments where outbound mail can't reach APP_URL (e.g. internal-only app URL).
Light/dark color-scheme meta tags added; PNGs use transparent backgrounds so they read on both white and dark email backgrounds.

⚠ Action required before merge — KnowAll AI logo

public/email/knowall-logo.png in this PR is a 480×120 transparent placeholder so the path resolves and CI passes. It needs to be replaced with the real KnowAll AI logo before this PR is merged.

How to upload the real logo

Locally on this branch:

git checkout fix/361-branded-email-templates
git pull

Replace the file: drop the real KnowAll AI logo as public/email/knowall-logo.png
- Format: PNG with transparent background
- Recommended source size: 480×120 (so it renders crisply at the 120×30 display size on retina displays)
- The aspect ratio doesn't have to be exactly 4:1 — the templates use width=120 height=30 only as hints; the image's natural aspect ratio is preserved by max-width: 100%; height: auto. But 4:1 will look the most balanced beside the ZapDesk logo.

Commit and push:

git add public/email/knowall-logo.png
git commit -m "Add KnowAll AI logo for outbound email footer"
git push

Re-render the local preview to confirm: bun run scripts/preview-email-templates.mjs then open email-preview.html.

(The ZapDesk logo at public/email/zapdesk-logo.png is already correct — it's auto-generated from public/assets/logo.svg. If logo.svg ever changes, regenerate via bun run scripts/generate-email-assets.mjs.)

Fixes

Fixes #361

Acceptance criteria

All four outbound email templates use the new branded header (ZapDesk logo)
All four outbound email templates use the new branded footer (KnowAll AI logo + link)
CTA button (View Ticket #N) matches the in-app primary button style (#22c55e, rounded, white text)
Logos rendered as <img> with explicit width/height to avoid layout shift in slow-rendering clients
Logo URLs configurable via env vars with sensible defaults pointing at ${APP_URL}/email/...
Email renders correctly in: Gmail web, Outlook desktop, Outlook web, Apple Mail (reviewer to verify after dropping in the real KnowAll logo)
Works in dark-mode email clients (reviewer to verify after dropping in the real KnowAll logo)

Files changed

src/lib/email-templates.ts — new branded layoutWrapper (logo header, KnowAll footer, refined CTA, dark-mode meta), exported so email.ts can reuse it.
src/lib/email.ts — sendTestEmail now uses layoutWrapper instead of inline HTML so the test email matches the rest.
public/email/zapdesk-logo.png — generated from public/assets/logo.svg.
public/email/knowall-logo.png — transparent placeholder, see action-required section above.
scripts/generate-email-assets.mjs — regenerator for the ZapDesk PNG.
scripts/preview-email-templates.mjs — renders all templates to a local email-preview.html (gitignored) for visual review.
.gitignore — exclude email-preview.html.
CLAUDE.md — documents ZAPDESK_LOGO_URL and KNOWALL_LOGO_URL.

New env vars

Variable	Purpose	Required
`ZAPDESK_LOGO_URL`	Override URL for the ZapDesk logo	No (default: `${APP_URL}/email/zapdesk-logo.png`)
`KNOWALL_LOGO_URL`	Override URL for the KnowAll AI logo	No (default: `${APP_URL}/email/knowall-logo.png`)

Test plan

Local preview (no email sent)

bun run scripts/preview-email-templates.mjs
Open email-preview.html in a browser. Confirm:
- ZapDesk logo renders at the top of every template (you'll need bun run dev running so localhost:3000/email/zapdesk-logo.png resolves).
- "View Ticket #1234" green CTA button.
- Footer shows the KnowAll logo (placeholder/blank for now) + "Powered by KnowAll AI" link to https://knowall.ai.
- Layout is consistent across all four sections.

Live email send

Ensure MAIL_* env vars and MAIL_FROM are set; restart bun run dev.
Sign in at http://localhost:3000, navigate to /admin, click "Send test email", enter your email address.
Expected: email arrives with the new branded layout — logo header, branded CTA, KnowAll footer.

Inbound-driven templates

Send a fresh email to the polled mailbox (no [ZapDesk #N] tag) → triggers sendTicketConfirmation → confirmation email lands in the customer inbox with new layout.
From the ticket UI, set the ticket status (active → resolved) → triggers sendStatusChangeNotification → status-change email lands with new layout.
From the ticket UI, send an agent reply → triggers sendAgentReply → reply email lands with new layout (and history block, if there's prior conversation).

Cross-client rendering check (after real logo is in place)

Send a test email to addresses on each client and verify logos render and layout holds:

Gmail web
Outlook desktop (Windows)
Outlook web (outlook.office.com)
Apple Mail
Bonus: dark-mode toggle in any of the above

Automated checks

bun run typecheck — passes
bun run lint — passes (4 pre-existing warnings, unrelated)
bunx prettier --check on changed files — passes

Out of scope

Per-tenant white-labelling (different brand per client).
Inline / embedded MIME attachments for logos — using hosted URLs is simpler and fine for v1.

🤖 Generated with Claude Code

…361) Outbound mail (ticket confirmation, agent reply, status change, test email) now picks up the same visual language as the ZapDesk UI and carries the KnowAll AI brand mark, so customers see branded support communication rather than a generic system notification. - Header: ZapDesk logo image (240x60 displayed, 480x120 source PNG generated from public/assets/logo.svg) replaces the text header. - Footer: KnowAll AI logo + "Powered by KnowAll AI" link, alongside the existing "Please reply to this email to update your ticket" line. - CTA button refined (12x24 padding, line-height: 1) so View Ticket buttons render the same in Outlook desktop and Gmail web. - Single layoutWrapper now used by all templates including the previously-inline sendTestEmail body. - Logo URLs are env-overridable (ZAPDESK_LOGO_URL, KNOWALL_LOGO_URL) for deployments where outbound mail can't reach APP_URL — defaults point at the new public/email/ assets so local dev works out of box. - Light/dark color-scheme meta added; logos use transparent backgrounds so they read correctly on both white and dark email backgrounds. - scripts/generate-email-assets.mjs regenerates the ZapDesk PNG from logo.svg via sharp; scripts/preview-email-templates.mjs renders all templates to a local email-preview.html (gitignored) for visual review without sending real mail. knowall-logo.png is shipped as a transparent placeholder — replace it with the real KnowAll AI logo before merge. Closes #361 Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Adding ZAPDESK_LOGO_URL and KNOWALL_LOGO_URL pushed the description and required columns past the existing padding. Re-run prettier to widen the columns so format:check passes on CI. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Copilot

Pull request overview

Updates outbound email rendering to use a shared branded HTML layout (ZapDesk logo header + KnowAll AI footer) across all core templates, and adds local tooling to preview/regenerate email assets.

Changes:

Exported and expanded layoutWrapper to include logo header/footer, CTA refinements, and light/dark color-scheme meta tags.
Updated sendTestEmail to reuse the shared email layout for consistency.
Added scripts to (a) generate email PNG assets from the main SVG and (b) render a local multi-template preview HTML, plus gitignore/docs updates.

Reviewed changes

Copilot reviewed 5 out of 8 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
src/lib/email.ts	Switches test email HTML to use the shared `layoutWrapper`.
src/lib/email-templates.ts	Adds branded header/footer and exports `layoutWrapper`; introduces env-overridable logo URLs and dark-mode meta tags.
scripts/preview-email-templates.mjs	New local preview generator that writes `email-preview.html` for visual review.
scripts/generate-email-assets.mjs	New asset generator using `sharp` to produce PNG email logos.
public/email/zapdesk-logo.png	Adds/updates the ZapDesk email logo PNG asset.
public/email/knowall-logo.png	Adds a KnowAll AI email logo asset (currently described as a placeholder in PR).
.gitignore	Ignores the generated `email-preview.html`.
CLAUDE.md	Documents the new logo URL environment variables.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

+// Minimal transparent placeholder so the path resolves in dev. Replace
+// before merge with the real KnowAll AI logo (PNG, transparent, ~480x120).
+await sharp({
+  create: {
+    width: 480,
+    height: 120,
+    channels: 4,
+    background: { r: 0, g: 0, b: 0, alpha: 0 },
+  },
+})
+  .png()
+  .toFile('public/email/knowall-logo.png');
+console.log('wrote public/email/knowall-logo.png (480x120 transparent placeholder)');


+| Variable                                  | Description                                                       | Required                                          |
+| ----------------------------------------- | ----------------------------------------------------------------- | ------------------------------------------------- |
+| `NEXTAUTH_URL`                            | Base URL of the application                                       | Yes                                               |
+| `NEXTAUTH_SECRET`                         | Secret for NextAuth encryption                                    | Yes                                               |
+| `AZURE_AD_CLIENT_ID`                      | Azure AD application client ID                                    | Yes                                               |
+| `AZURE_AD_CLIENT_SECRET`                  | Azure AD application client secret                                | Yes                                               |
+| `AZURE_AD_TENANT_ID`                      | Azure AD tenant ID (or 'common')                                  | Yes                                               |
+| `AZURE_DEVOPS_ORG`                        | Azure DevOps organization name                                    | Yes                                               |
+| `AZURE_DEVOPS_PAT`                        | Personal Access Token for service account                         | For email integration                             |
+| `EMAIL_WEBHOOK_SECRET`                    | Shared secret for `/api/email/poll` and `/api/email/webhook`      | For email integration                             |
+| `MAIL_POLL_MAILBOX`                       | Mailbox ZapDesk polls for inbound email                           | For inbound email                                 |
+| `MAIL_FROM`                               | Sender address for outbound mail                                  | For outbound email                                |
+| `MAIL_FROM_NAME`                          | Display name for outbound mail                                    | No (default: ZapDesk Support)                     |
+| `MAIL_TENANT_ID`                          | Tenant ID for the dedicated mail Azure AD app                     | For email integration                             |
+| `MAIL_CLIENT_ID`                          | Client ID for the dedicated mail Azure AD app                     | For email integration                             |
+| `MAIL_CLIENT_SECRET`                      | Client secret for the dedicated mail Azure AD app                 | For email integration                             |
+| `ZAPDESK_LOGO_URL`                        | Override URL for the ZapDesk logo in outbound email               | No (default: `${APP_URL}/email/zapdesk-logo.png`) |
+| `KNOWALL_LOGO_URL`                        | Override URL for the KnowAll AI logo in the outbound email footer | No (default: `${APP_URL}/email/knowall-logo.png`) |


- Guard knowall-logo.png from being overwritten by the asset script: only write the transparent placeholder if the file does not already exist, so re-running the script never clobbers the real logo once it is dropped in. - Document APP_URL in CLAUDE.md env-var table — it controls the base URL for outbound email links and asset paths (falls back to NEXTAUTH_URL), which ZAPDESK_LOGO_URL / KNOWALL_LOGO_URL defaults reference. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Ayush and others added 4 commits May 9, 2026 20:44

Merge branch 'main' into fix/361-branded-email-templates

dbf9623

Merge branch 'main' into fix/361-branded-email-templates

a327983

EdiWeeks requested a review from Copilot May 18, 2026 15:47

Merge branch 'main' into fix/361-branded-email-templates

a02d476

Copilot started reviewing on behalf of EdiWeeks May 18, 2026 15:47 View session

Copilot AI reviewed May 18, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

fix: brand outbound email templates with ZapDesk + KnowAll AI logos#378

fix: brand outbound email templates with ZapDesk + KnowAll AI logos#378
akash2017sky wants to merge 6 commits into
mainfrom
fix/361-branded-email-templates

akash2017sky commented May 9, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

akash2017sky commented May 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

⚠ Action required before merge — KnowAll AI logo

How to upload the real logo

Fixes

Acceptance criteria

Files changed

New env vars

Test plan

Local preview (no email sent)

Live email send

Inbound-driven templates

Cross-client rendering check (after real logo is in place)

Automated checks

Out of scope

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

akash2017sky commented May 9, 2026 •

edited

Loading