Merge pull request #90 from goposta/dev

feat(email): add hosted web view and reserved {{ posta_* }} template …

Author: jkaninda

docs/docs/templates/system-variables.md

@@ -0,0 +1,64 @@
+---
+sidebar_position: 3
+title: System Variables
+description: Built-in {{ posta_* }} template variables for unsubscribe and web-view links
+---
+
+# System Variables
+
+Posta reserves the `{{ posta_* }}` variable namespace for values it injects into
+every templated email. You don't pass these in `template_data` — Posta fills them
+in per message, after the message identity is known. Using them is opt-in: a
+variable only appears if your template references it.
+
+> The `posta_` prefix is reserved. Any key you supply in `template_data` that starts
+> with `posta_` is ignored in favour of the system value.
+
+## Available variables
+
+| Variable | Description |
+|---|---|
+| `{{ posta_web_view_url }}` | Signed link to read this email on the web ("view in browser"). |
+| `{{ posta_mail_web_link }}` | Alias for `posta_web_view_url`. |
+| `{{ posta_unsubscribe_url }}` | One-click unsubscribe link for this message. |
+
+## View in browser
+
+```html
+<a href="{{ posta_web_view_url }}">View this email in your browser</a>
+```
+
+Works in the text part too:
+
+```
+View online: {{ posta_web_view_url }}
+```
+
+The link is an HMAC-signed, **expiring** capability bound to the message's opaque
+ID. The hosted page renders the exact HTML that was sent, on Posta's public web
+origin (`POSTA_WEB_URL`), with a restrictive content-security policy, `noindex`, and
+no cookies. Opening it does **not** count as an email open.
+
+Notes:
+- Links expire after 90 days by default.
+- `cid:` inline-attachment images don't resolve on the web — use `https`/`data:` image URLs if you rely on the web view.
+
+## Unsubscribe
+
+```html
+<a href="{{ posta_unsubscribe_url }}">Unsubscribe</a>
+```
+
+For campaign sends this unsubscribes the recipient from that campaign's list. For
+transactional sends it adds the recipient to your suppression list. The link is the
+RFC 8058 one-click endpoint, so it also works from the mailbox-provider
+"Unsubscribe" button.
+
+## Behaviour in previews
+
+In the template editor / preview there is no real message yet, so each system
+variable renders as **its own name** (e.g. `{{ posta_web_view_url }}` →
+`posta_web_view_url`) rather than a generated link. This lets a preview of a
+template that uses system variables render without errors, and shows the author
+which variable sits where. The real links are only generated when the message is
+actually sent.

internal/handlers/template_handler.go

@@ -199,6 +199,10 @@ func (h *TemplateHandler) Preview(c *okapi.Context, req *PreviewTemplateRequest)
 	if data == nil {
 		data = map[string]any{}
 	}
+	// Expose reserved {{ posta_* }} variables by name so previews of templates that
+	// use them render without missing-key errors. No real message exists here, so
+	// they resolve to their own names rather than generated links.
+	data = email.WithSystemVarNames(data)
 
 	input := &email.RenderInput{
 		SubjectTemplate: req.Body.SubjectTemplate,

internal/handlers/tracking_handler.go

@@ -21,6 +21,7 @@ import (
 	"fmt"
 	"html"
 	"net/http"
+	"regexp"
 	"strings"
 	"time"
 
@@ -30,6 +31,11 @@ import (
 	"github.com/jkaninda/okapi"
 )
 
+// openPixelRe matches the open-tracking pixel injected by tracking.ProcessHTML so
+// it can be stripped from the hosted "view in browser" page — rendering a stored
+// campaign body in a browser would otherwise re-fire the open and inflate metrics.
+var openPixelRe = regexp.MustCompile(`(?i)<img[^>]+src=["'][^"']*/t/o/[^"']*["'][^>]*>`)
+
 type TrackingHandler struct {
 	trackingRepo    *repositories.TrackingRepository
 	messageRepo     *repositories.CampaignMessageRepository
@@ -78,6 +84,10 @@ type TrackingUnsubscribeRequest struct {
 	Token string `param:"token"`
 }
 
+type TrackingWebViewRequest struct {
+	Token string `param:"token"`
+}
+
 // OpenPixel serves a 1x1 transparent GIF and records the open event.
 // Signature is mandatory; unsigned or bad-sig requests get 404.
 func (h *TrackingHandler) OpenPixel(c *okapi.Context, req *TrackingOpenRequest) error {
@@ -216,6 +226,42 @@ h1{font-size:20px;color:#16a34a}p{color:#6b7280;font-size:14px}</style></head><b
 	return c.HTMLView(http.StatusOK, confirmHTML, okapi.M{})
 }
 
+// WebView renders a hosted copy of a sent email ("view in browser"). The token is
+// an HMAC-signed, expiring capability bound to the email's opaque UUID. Because the
+// page renders arbitrary customer HTML, it is served with a restrictive CSP, no
+// cookies, and noindex, and the open-tracking pixel is stripped so a web view does
+// not inflate open metrics.
+func (h *TrackingHandler) WebView(c *okapi.Context, req *TrackingWebViewRequest) error {
+	emailUUID, err := h.trackingService.VerifyWebViewToken(req.Token)
+	if err != nil {
+		return c.HTMLView(http.StatusNotFound, "This link is invalid or has expired.", okapi.M{})
+	}
+	em, err := h.emailRepo.FindByUUID(emailUUID)
+	if err != nil || em == nil {
+		return c.HTMLView(http.StatusNotFound, "Message not found", okapi.M{})
+	}
+
+	body := em.HTMLBody
+	if strings.TrimSpace(body) == "" {
+		body = "<pre style=\"white-space:pre-wrap;font-family:sans-serif\">" + html.EscapeString(em.TextBody) + "</pre>"
+	}
+	body = openPixelRe.ReplaceAllString(body, "")
+
+	hdr := c.ResponseWriter().Header()
+	hdr.Set("Content-Security-Policy", "default-src 'none'; img-src https: http: data:; style-src 'unsafe-inline' https:; font-src https: data:; base-uri 'none'; form-action 'none'")
+	hdr.Set("X-Robots-Tag", "noindex, nofollow")
+	hdr.Set("Referrer-Policy", "no-referrer")
+
+	page := fmt.Sprintf(`<!DOCTYPE html><html lang="en"><head><meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1"><meta name="robots" content="noindex, nofollow">
+<title>%s</title>
+<style>body{margin:0;background:#f3f4f6}.posta-wv-bar{font-family:sans-serif;font-size:12px;color:#6b7280;text-align:center;padding:10px;background:#fff;border-bottom:1px solid #e5e7eb}.posta-wv-body{max-width:680px;margin:0 auto;padding:16px}</style>
+</head><body><div class="posta-wv-bar">You are viewing a copy of an email.</div><div class="posta-wv-body">%s</div></body></html>`,
+		html.EscapeString(em.Subject), body)
+
+	return c.HTMLView(http.StatusOK, page, okapi.M{})
+}
+
 // UnsubscribeConfirm processes the unsubscribe action.
 func (h *TrackingHandler) UnsubscribeConfirm(c *okapi.Context, req *TrackingUnsubscribeRequest) error {
 	messageID, err := h.trackingService.VerifyUnsubscribeToken(req.Token)

internal/routes/routes.go

@@ -325,10 +325,10 @@ func InitRoutes(app *okapi.Okapi, db *gorm.DB, redisClient *redis.Client, cfg *c
 	trackingService := tracking.NewService(trackingRepo, cfg.AppWebURL, []byte(cfg.JWTSecret))
 	r.h.tracking = handlers.NewTrackingHandler(trackingRepo, campaignMessageRepo, campaignRepo, subscriberRepo, subscriberListRepo, emailRepo, suppressionRepo, trackingService)
 
-	// Auto-attach RFC 8058 one-click unsubscribe URLs on transactional sends
-	// that target a subscriber list (so Gmail/Yahoo bulk-sender requirements
-	// are met without the caller having to build the header themselves).
-	emailService.SetTxUnsubscribeGenerator(trackingService)
+	// Wire the generator for Posta-injected public links (one-click unsubscribe +
+	// hosted "view in browser"), used to resolve reserved {{ posta_* }} template
+	// variables once an email's identity is known.
+	emailService.SetLinkGenerator(trackingService)
 
 	// Bounce webhook
 	r.h.bounceWebhook = handlers.NewBounceWebhookHandler(subscriberRepo, emailRepo, campaignMessageRepo)

internal/routes/tracking_routes.go

@@ -75,6 +75,14 @@ func (r *Router) trackingRoutes() []okapi.RouteDefinition {
 			Summary: "Transactional one-click unsubscribe (RFC 8058)",
 			Options: []okapi.RouteOption{okapi.DocHide()},
 		},
+		{
+			Method:  http.MethodGet,
+			Path:    "/t/v/{token}",
+			Handler: okapi.H(r.h.tracking.WebView),
+			Tags:    []string{"Tracking"},
+			Summary: "View email in browser",
+			Options: []okapi.RouteOption{okapi.DocHide()},
+		},
 	}
 }
 

internal/services/email/service.go

@@ -28,6 +28,7 @@ import (
 	"strings"
 	"time"
 
+	"github.com/google/uuid"
 	"github.com/goposta/posta/internal/models"
 	"github.com/goposta/posta/internal/services/ratelimit"
 	"github.com/goposta/posta/internal/services/settings"
@@ -64,11 +65,13 @@ type PlanLimits struct {
 	MaxBatchSize        int
 }
 
-// TxUnsubscribeGenerator produces a signed one-click (RFC 8058) unsubscribe
-// URL for a transactional email. Kept as a narrow interface so the email
-// service does not depend directly on the tracking package.
-type TxUnsubscribeGenerator interface {
+// LinkGenerator produces the signed public links Posta injects into messages:
+// the one-click (RFC 8058) unsubscribe URL and the hosted "view in browser" URL.
+// Kept as a narrow interface so the email service does not depend directly on the
+// tracking package.
+type LinkGenerator interface {
 	TxUnsubscribeURL(emailID uint) string
+	WebViewURL(emailUUID string) string
 }
 
 type Service struct {
@@ -89,7 +92,7 @@ type Service struct {
 	settings         *settings.Provider
 	blobStore        blob.Store
 	planLimits       PlanLimitsProvider
-	txUnsubGen       TxUnsubscribeGenerator
+	linkGen          LinkGenerator
 	devMode          bool
 	onSent           func()
 	onFailed         func()
@@ -151,11 +154,11 @@ func (s *Service) SetEnqueuer(eq EmailEnqueuer) {
 	s.enqueuer = eq
 }
 
-// SetTxUnsubscribeGenerator wires the one-click unsubscribe URL generator.
-// When set, transactional sends that use a subscriber list but don't supply an
-// explicit list_unsubscribe_url will get an auto-generated RFC 8058 URL.
-func (s *Service) SetTxUnsubscribeGenerator(gen TxUnsubscribeGenerator) {
-	s.txUnsubGen = gen
+// SetLinkGenerator wires the generator for Posta-injected public links — the
+// one-click unsubscribe URL and the hosted "view in browser" URL used to resolve
+// reserved {{ posta_* }} template variables.
+func (s *Service) SetLinkGenerator(gen LinkGenerator) {
+	s.linkGen = gen
 }
 
 // SetBlobStore sets the blob storage backend for persisting email attachments.
@@ -602,6 +605,10 @@ func (s *Service) Send(ctx context.Context, userID, apiKeyID uint, workspaceID *
 	}
 
 	em := &models.Email{
+		// Assign the UUID up front so reserved {{ posta_* }} links (which key the
+		// web view off the UUID) can be built without depending on the DB reading
+		// the gen_random_uuid() default back after insert.
+		UUID:                uuid.NewString(),
 		UserID:              userID,
 		WorkspaceID:         workspaceID,
 		APIKeyID:            apiKeyPtr,
@@ -623,6 +630,23 @@ func (s *Service) Send(ctx context.Context, userID, apiKeyID uint, workspaceID *
 		return nil, fmt.Errorf("failed to store email: %w", err)
 	}
 
+	// Resolve reserved {{ posta_* }} system links now that the email identity is
+	// known. Rendering left sentinels in the body; replace them with the real
+	// per-message URLs. Only touches the DB when the template actually used one.
+	if s.linkGen != nil && (HasSystemSentinels(em.HTMLBody) || HasSystemSentinels(em.TextBody) || HasSystemSentinels(em.Subject)) {
+		webViewURL := s.linkGen.WebViewURL(em.UUID)
+		unsubscribeURL := s.linkGen.TxUnsubscribeURL(em.ID)
+		em.HTMLBody = SubstituteSystemLinks(em.HTMLBody, webViewURL, unsubscribeURL)
+		em.TextBody = SubstituteSystemLinks(em.TextBody, webViewURL, unsubscribeURL)
+		em.Subject = SubstituteSystemLinks(em.Subject, webViewURL, unsubscribeURL)
+		// Keep req in sync so the synchronous fallback (sendSync) sends the
+		// resolved body/subject too.
+		req.HTML = em.HTMLBody
+		req.Text = em.TextBody
+		req.Subject = em.Subject
+		_ = s.emailRepo.Update(em)
+	}
+
 	if s.devMode {
 		em.Status = models.EmailStatusSent
 		now := time.Now()
@@ -1003,7 +1027,17 @@ func (s *Service) RenderTemplate(userID uint, workspaceID *uint, templateID *uin
 	if err != nil {
 		return nil, fmt.Errorf("template not found: %w", err)
 	}
-	return s.resolveAndRender(tmpl, language, data)
+	rendered, err := s.resolveAndRender(tmpl, language, data)
+	if err != nil {
+		return nil, err
+	}
+	// This is a preview (editor / dry-run): there is no real message yet, so show
+	// the reserved {{ posta_* }} variables by name rather than leaking the internal
+	// sentinels or generating throwaway links.
+	rendered.HTML = SubstituteSystemLinks(rendered.HTML, VarWebView, VarUnsubscribe)
+	rendered.Text = SubstituteSystemLinks(rendered.Text, VarWebView, VarUnsubscribe)
+	rendered.Subject = SubstituteSystemLinks(rendered.Subject, VarWebView, VarUnsubscribe)
+	return rendered, nil
 }
 
 // findTemplate looks up a template by ID or name. When templateID is provided
@@ -1067,7 +1101,9 @@ func (s *Service) resolveAndRender(tmpl *models.Template, language string, data
 		TextTemplate:    l.TextTemplate,
 		CSS:             css,
 	}
-	return s.renderer.Render(input, data)
+	// Inject reserved {{ posta_* }} variables as sentinels; the real per-message
+	// URLs are substituted later in Send once the email identity is known.
+	return s.renderer.Render(input, WithSystemVars(data))
 }
 
 // resolveLocalization implements the language fallback strategy: