mailtemplates

package
v0.8.7 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 29, 2026 License: Apache-2.0 Imports: 10 Imported by: 0

Documentation

Overview

Package mailtemplates renders the platform's emails: a token registry, a {{token}} substitution engine with no code execution, a small safe markup and one shared branded layout around every event template.

Index

Constants

View Source 
const (
	EnvMaxLogoURL       = "APP_EMAIL_BRANDING_MAX_LOGO_URL"
	EnvMaxFooterText    = "APP_EMAIL_BRANDING_MAX_FOOTER_TEXT"
	EnvMaxFooterAddress = "APP_EMAIL_BRANDING_MAX_FOOTER_ADDRESS"
	EnvMaxFooterLinks   = "APP_EMAIL_BRANDING_MAX_FOOTER_LINKS"
	EnvMaxLinkLabel     = "APP_EMAIL_BRANDING_MAX_LINK_LABEL"
)

Env names for the branding caps; each falls back to the default below when unset or invalid.

View Source 
const (
	CategorySystem       = "system"
	CategoryAnnouncement = "announcement"
)

Event categories. System mail is security or account related and ignores the opt-out list; announcements honor it and carry an unsubscribe link.

View Source 
const (
	EventPasswordReset      = "password_reset"
	EventUserInvite         = "user_invite"
	EventLoginCode          = "login_code"
	EventSignInAlert        = "signin_alert"
	EventEmailChanged       = "email_changed"
	EventEmailChangeConfirm = "email_change_confirm"
	EventAlertNotification  = "alert_notification"
	EventCertExpiry         = "cert_expiry_alert"
	EventCertExpiryPlain    = "cert_expiry_alert_plain"
	EventDeployNotification = "deploy_notification"
	EventDeployApproval     = "deploy_approval"
	EventTestEmail          = "test_email"
	EventAnnouncement       = "announcement"
	EventMaintenanceNotice  = "maintenance_notice"
)

Event keys.

View Source 
const (
	ScopeGlobal    = "global"
	ScopeRecipient = "recipient"
	ScopeEvent     = "event"
)

Token scopes.

Variables

This section is empty.

Functions

func EventKeys 

func EventKeys() []string

EventKeys returns the sorted event keys.

func ForceScheme 

func ForceScheme(page, scheme string) string

ForceScheme pins a rendered page to "light" or "dark" for previews; any other value leaves the page following the viewer's own setting.

func GlobalValues 

func GlobalValues(b Branding, now time.Time) map[string]string

GlobalValues returns the global-scope token values for b.

func SampleValues 

func SampleValues() map[string]string

SampleValues returns every token's sample value, for previews.

func SubstituteText 

func SubstituteText(text string, values map[string]string) string

SubstituteText fills tokens for a plain-text field such as a subject. Line breaks in values are flattened so a value cannot extend a header.

func ValidateBranding 

func ValidateBranding(b EmailBranding, lim BrandingLimits) error

ValidateBranding refuses anything unsafe or oversized; it is the single save-time gate.

func ValidateHTTPSURL 

func ValidateHTTPSURL(raw string, maxLen int) error

ValidateHTTPSURL accepts an empty string or an https URL with a host, no credentials and no whitespace or control characters. The server never fetches it; it only lands in an href or img src.

func ValidateLayout 

func ValidateLayout(l Layout) error

ValidateLayout checks the header image is an https URL and the footer only uses global tokens.

func ValidateTemplate 

func ValidateTemplate(e Event, t Template) error

ValidateTemplate checks the subject, preheader and body against the tokens e supports.

func ValidateTokens 

func ValidateTokens(text string, allowed []string) error

ValidateTokens reports every token in text that is malformed or not in allowed. Saving a template with any of these is refused.

Types

type Branding 

type Branding struct {
	Name             string
	PrimaryColor     string
	PrimaryColorDark string
	SupportEmail     string
	DashboardURL     string
	InstanceName     string
}

Branding is the identity the layout wears, filled from the brand layer.

type BrandingLimits 

type BrandingLimits struct {
	MaxLogoURL       int
	MaxFooterText    int
	MaxFooterAddress int
	MaxFooterLinks   int
	MaxLinkLabel     int
}

BrandingLimits caps the size of each branding field.

func LimitsFromEnv 

func LimitsFromEnv() BrandingLimits

LimitsFromEnv reads the branding caps from the environment.

type EmailBranding 

type EmailBranding struct {
	LogoURL       string       `json:"logo_url"`
	BrandColor    string       `json:"brand_color"`
	FooterText    string       `json:"footer_text"`
	FooterAddress string       `json:"footer_address"`
	FooterLinks   []FooterLink `json:"footer_links"`
	ShowPoweredBy bool         `json:"show_powered_by"`
}

EmailBranding is what an operator controls about how every rich email looks. The footer is structured text plus allowlisted links: there is deliberately no raw HTML field.

func (EmailBranding) Layout 

func (b EmailBranding) Layout() Layout

Layout turns validated branding into the layout the renderer wears.

type Event 

type Event struct {
	Key         string   `json:"key"`
	Label       string   `json:"label"`
	Description string   `json:"description"`
	Category    string   `json:"category"`
	Tokens      []string `json:"tokens"`
	Default     Template `json:"default"`
}

Event is one kind of email the platform sends.

func Events 

func Events() []Event

Events returns every event definition, in a stable order.

func LookupEvent 

func LookupEvent(key string) (Event, bool)

LookupEvent finds an event by key. 

type FooterLink struct {
	Label string `json:"label"`
	URL   string `json:"url"`
}

FooterLink is one labelled https link in the email footer.

type Layout 

type Layout struct {
	HeaderImageURL string       `json:"header_image_url"`
	FooterText     string       `json:"footer_text"`
	FooterAddress  string       `json:"footer_address,omitempty"`
	FooterLinks    []FooterLink `json:"footer_links,omitempty"`
	ShowPoweredBy  bool         `json:"show_powered_by,omitempty"`
}

Layout is the operator-editable frame around every event template.

type Options 

type Options struct {
	// UnsubscribeURL, when set, adds the unsubscribe line to the footer.
	UnsubscribeURL string
}

Options carries per-message values the layout needs.

type Rendered 

type Rendered struct {
	Subject   string `json:"subject"`
	Preheader string `json:"preheader"`
	Text      string `json:"text"`
	HTML      string `json:"html"`
}

Rendered is a finished message.

func Render 

func Render(b Branding, l Layout, t Template, values map[string]string, o Options) Rendered

Render produces the subject, plain text and HTML for t inside the shared layout. Values are escaped for HTML, so a value can never add markup.

type Template 

type Template struct {
	Subject   string `json:"subject"`
	Preheader string `json:"preheader"`
	Body      string `json:"body"`
}

Template is the editable part of an email.

type Token 

type Token struct {
	Name        string `json:"name"`
	Description string `json:"description"`
	Sample      string `json:"sample"`
	Scope       string `json:"scope"`
}

Token is one substitutable value.

func LookupToken 

func LookupToken(name string) (Token, bool)

LookupToken finds a token by name.

func Tokens 

func Tokens() []Token

Tokens returns every registered token, sorted by scope then name.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.