transactional

package
v1.2.0 Latest Latest
Warning

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

Go to latest
Published: Oct 30, 2026 License: AGPL-3.0 Imports: 61 Imported by: 0

Documentation

Overview

Package transactional is ReputeCast's transactional email (design expansion phase 1): templates with declared variables, named test data and published versions; the send, batch and render API with idempotency keys; the message log with its timeline; categories and their opt-outs; the Transactional settings; delivery alerts and retention.

Transactional mail is its own stream: it goes through the Transactional route (internal/routing) with automatic failover, honours only the suppressions that apply to all mail (internal/suppressions), and is delivered by the sending engine's transactional outbox within each provider's shared rate, ahead of Broadcasts.

Only published versions are ever sent. Sensitive variables are never stored: the message log and stored content show them as ••••••, and the sealed delivery payload is deleted once a provider accepted the message.

Index

Constants

View Source
const (
	AlertBounceRate     = "bounce_rate"
	AlertFailed         = "failed"
	AlertMedianDelivery = "median_delivery"
	AlertFailover       = "failover"
)

Alert kinds.

View Source
const (
	KindEssential = "essential"
	KindOptional  = "optional"
)

Category kinds.

View Source
const (
	SevBlock = "block"
	SevWarn  = "warn"
	SevInfo  = "info"
	SevPass  = "pass"
)

Check severities.

View Source
const (
	EventSent       = "message.sent"
	EventDelivered  = "message.delivered"
	EventDeferred   = "message.deferred"
	EventBounced    = "message.bounced"
	EventComplained = "message.complained"
	EventRejected   = "message.rejected"
	EventFailed     = "message.failed"
	EventOpened     = "message.opened"
	EventClicked    = "message.clicked"
)

Webhook events of the "Transactional messages" group. Each carries the message's tags and metadata.

View Source
const (
	SoftBounceLimit  = 3
	SoftBounceWindow = 7 * 24 * time.Hour
)

SoftBounceLimit soft bounces in SoftBounceWindow put an address on the suppression list ("Soft bounces don't suppress the address; three in 7 days would.").

View Source
const (
	Period24h = "24h"
	Period7d  = "7d"
	Period30d = "30d"
)

Periods of the numbers.

View Source
const (
	MetadataRetentionDays = 90
	// ExportMax is the most rows one CSV export carries.
	ExportMax = 50000
)

Retention of the message log: metadata and events.

View Source
const (
	OptOutPreferenceCenter = "preference_center"
	OptOutUnsubscribeLink  = "unsubscribe_link"
	OptOutOneClick         = "one_click"
)

Where an opt-out came from.

View Source
const (
	MaxBatch       = 100
	MaxScheduleAge = 72 * time.Hour
	// IdempotencyTTL is how long an idempotency key is remembered.
	IdempotencyTTL = 24 * time.Hour
)

Sending limits.

View Source
const (
	CodeTemplateNotFound     = "template_not_found"
	CodeTemplateNotPublished = "template_not_published"
	CodeMissingVariables     = "missing_variables"
	CodeInvalidRecipient     = "invalid_recipient"
	CodeRecipientSuppressed  = "recipient_suppressed"
	CodeSenderNotVerified    = "sender_not_verified"
	CodeAttachmentsTooLarge  = "attachments_too_large"
	CodeRateLimited          = "rate_limited"
	CodeNoHealthyRoute       = "no_healthy_route"
	// CodeIdempotencyReused answers a key sent again with another body.
	CodeIdempotencyReused = "idempotency_key_reused"
	// CodeTemplateNotAllowed answers a key limited to other templates.
	CodeTemplateNotAllowed = "template_not_allowed"
	// Template editing.
	CodeVersionConflict   = "version_conflict"
	CodeBreakingChange    = "breaking_change"
	CodeApprovalRequired  = "approval_required"
	CodeTemplateDoesntRun = "template_does_not_render"
	CodeAgentsNeverSend   = "agents_never_send"
)

Error codes of the transactional API (brief §3.2). Each answer says in its detail what to fix.

View Source
const (
	TypeText    = "text"
	TypeNumber  = "number"
	TypeBoolean = "boolean"
	TypeDate    = "date"
	TypeURL     = "url"
	TypeList    = "list"
	TypeObject  = "object"
)

Variable types (brief §3.1).

View Source
const AlertMinSample = 20

AlertMinSample is how many messages an hour needs before its bounce rate or median delivery time can raise an alert (one bounce out of three sends isn't a trend).

View Source
const Base = "/workspaces/{workspace}/transactional"

Base is the path of every transactional operation.

View Source
const BreakingWindow = 7 * 24 * time.Hour

BreakingWindow is how far back the breaking-change check reads calls.

View Source
const GroupAccessibility = "Accessibility"

GroupAccessibility is the checks' Accessibility group.

View Source
const KeepDraftRevisions = 100

KeepDraftRevisions is how many earlier draft revisions a template keeps.

View Source
const Mask = "••••••"

Mask replaces a sensitive value wherever it would be stored or shown.

View Source
const MaxRawRecipients = 50

MaxRawRecipients is how many recipients one SMTP message may have.

View Source
const RejectedCallRetention = 30 * 24 * time.Hour

RejectedCallRetention is how long refused calls are kept.

Variables

View Source
var (
	ErrSMTPAuthFailed      = errors.New("the username or password is wrong: the username is the credential's ID and the password its secret, both shown once when it was created")
	ErrSMTPNotSMTPKey      = errors.New("this key is an API key; create an SMTP credential in Transactional › Setup")
	ErrSMTPKeyRevoked      = errors.New("this SMTP credential was revoked; create a new one in Transactional › Setup")
	ErrSMTPKeyExpired      = errors.New("this SMTP credential has expired; create a new one in Transactional › Setup")
	ErrSMTPCannotSend      = errors.New("this credential doesn't hold transactional:send")
	ErrSMTPWorkspaceGone   = errors.New("the credential's workspace was deleted")
	ErrSMTPCreatorLeft     = errors.New("the person who created this credential is no longer an active member of the workspace; create a new one in Transactional › Setup")
	ErrSMTPCreatorCantSend = errors.New("the person who created this credential no longer holds transactional:send; create a new one in Transactional › Setup")
	// ErrSMTPIntegrationKey: an integration's key (Zapier, Make, n8n,
	// WordPress) only calls its own integration's operations.
	ErrSMTPIntegrationKey = errors.New("this key belongs to an integration, which can only call its own operations; create an SMTP credential in Transactional › Setup")
)

Errors of SMTP authentication; their text is the SMTP reply's.

View Source
var OptOutReasons = []struct{ Value, Label string }{
	{"too_often", "Too often"},
	{"not_useful", "Not useful to me"},
	{"in_app", "I read this in the app"},
	{"other", "Other"},
}

OptOutReasons are the answers to "Why did you turn it off?".

Functions

func DemoHash

func DemoHash(t DemoTemplate, sender *uuid.UUID, replyTo string, opens, clicks bool) string

DemoHash is the content hash a published version keeps, equal to its draft's when nothing changed since.

func DemoRender

func DemoRender(t DemoTemplate, data map[string]any, toEmail, toName string, links map[string]string) (subject, html, text string, err error)

DemoRender renders what a message's log keeps: sensitive values masked.

func EmitMessage

func EmitMessage(ctx context.Context, tx pgx.Tx, wsID uuid.UUID, slug string, id uuid.UUID, event, reason string, at time.Time) error

EmitMessage queues a message.* webhook event for a transactional message (the sending engine and webhook ingest call it through the hooks). reason overrides the message's error ("452 4.2.2 mailbox full").

func KeyFromName

func KeyFromName(name string) string

KeyFromName turns "Password reset" into "password-reset".

func RegisterJobs

func RegisterJobs(reg *jobs.Registry, s *Service)

RegisterJobs adds the transactional domain's jobs.

func RegisterMessages

func RegisterMessages(h huma.API, s *Service)

RegisterMessages adds the message log operations.

func RegisterSending

func RegisterSending(h huma.API, s *Service)

RegisterSending adds the send and batch operations.

func RegisterTemplates

func RegisterTemplates(h huma.API, s *Service)

RegisterTemplates adds the template, category and settings operations.

func StarterDemo

func StarterDemo(key, product, address string) (DemoTemplate, []TransactionalTestData, error)

StarterDemo is a starter's content for the demo data: subject, preheader and MJML with the product name and the address filled in, compiled.

Types

type AccessibilityChecker

type AccessibilityChecker interface {
	TemplateChecks(ctx context.Context, wsID, templateID uuid.UUID, mjml, html string) ([]TransactionalCheck, error)
}

AccessibilityChecker runs the accessibility checks on a template's content (internal/accessibility), as findings of the Accessibility group.

type AlertsArgs

type AlertsArgs struct{}

AlertsArgs checks the delivery alerts.

func (AlertsArgs) InsertOpts

func (AlertsArgs) InsertOpts() river.InsertOpts

InsertOpts implements river.JobArgsWithInsertOpts.

func (AlertsArgs) Kind

func (AlertsArgs) Kind() string

Kind implements river.JobArgs.

type AlertsWorker

type AlertsWorker struct {
	river.WorkerDefaults[AlertsArgs]
	S *Service
}

AlertsWorker runs AlertsArgs.

func (*AlertsWorker) Timeout

func (w *AlertsWorker) Timeout(*river.Job[AlertsArgs]) time.Duration

Timeout bounds one check.

func (*AlertsWorker) Work

func (w *AlertsWorker) Work(ctx context.Context, _ *river.Job[AlertsArgs]) error

Work implements river.Worker.

type CategoryPath

type CategoryPath struct {
	api.WorkspaceInput
	CategoryID string `path:"categoryId" format:"uuid"`
}

CategoryPath names a category.

type DemoTemplate

type DemoTemplate struct {
	Subject, Preheader string
	MJML, HTML         string
	Variables          []TransactionalVariable
}

DemoTemplate is a template version's content.

func (*DemoTemplate) Compile

func (t *DemoTemplate) Compile() error

Compile fills HTML from the MJML, as saving a draft does.

type LanguageChoice

type LanguageChoice struct {
	// Language is the version's language.
	Language string
	// Reason is why: match (the contact's language, or the one asked for),
	// requested (asked for a language without a version), no_language,
	// not_offered, missing, draft or held.
	Reason string
	// Contact is the language code asked for, else the contact's.
	Contact string
	// Content replaces the template version's when the version isn't the
	// source; nil for the source.
	Content *TranslationText
}

LanguageChoice is the language version a message uses and why.

type LogFilter

type LogFilter struct {
	Status   string
	Template string
	Provider string
	Key      string
	Range    string // 1h, 24h, 7d, 30d, custom
	From, To string // custom dates (YYYY-MM-DD, the workspace's time zone)
	Query    string
	Before   string
	After    string
	Limit    int
}

LogFilter narrows the log.

type MailboxClassifier

type MailboxClassifier interface {
	ForEmail(ctx context.Context, email string) mailbox.Class
}

MailboxClassifier is the part of mailbox.Classifier transactional sends use.

type MessagePath

type MessagePath struct {
	api.WorkspaceInput
	MessageID string `path:"messageId" maxLength:"36" doc:"The message ID the send API answered"`
}

MessagePath names a message.

type NotificationCategory

type NotificationCategory struct {
	ID          uuid.UUID
	Name        string
	Description string
	On          bool
	// OptedOutAt and Source say when and how it was turned off.
	OptedOutAt *time.Time
	Source     string
}

NotificationCategory is one Optional category for an address.

type NotificationMessage

type NotificationMessage struct {
	Email        string
	CategoryID   *uuid.UUID
	CategoryName string
	// Optional is true when the category can be turned off.
	Optional bool
	// Product is how recipients know the sender ("Acme Cloud").
	Product string
}

NotificationMessage is the transactional message a public link came with: its recipient and category.

type NotificationSet

type NotificationSet struct {
	Product    string
	Categories []NotificationCategory
}

NotificationSet is the preference center's "Notifications from …" section for an address.

type Problem

type Problem struct {
	api.Problem
	Missing []string `json:"missing,omitempty" doc:"Required variables the call didn't send (missing_variables)"`
}

Problem is an RFC 9457 answer of the transactional API: the API's problem plus the variables a call is missing ("missing": ["reset_url"]).

func (*Problem) WithMetaProblem

func (p *Problem) WithMetaProblem(kv ...any) *Problem

WithMetaProblem adds structured details to a transactional problem.

type PublishDecision

type PublishDecision struct {
	Allowed bool
	// NeedsApproval is true when the rule applies and no approval covers
	// this draft yet; Approvers names who can approve.
	NeedsApproval bool
	Approvers     []string
	// Reason is shown in the publish dialog ("The workspace rule … is on").
	Reason string
	// ApprovalID is the approval request that allowed the publish, if any.
	ApprovalID string
}

PublishDecision is a gate's answer.

type PublishGate

type PublishGate interface {
	// Check says whether the publish may go ahead. It runs inside the
	// publish transaction (q is that transaction) and again, read-only, for
	// the publish dialog.
	Check(ctx context.Context, q *store.Queries, req PublishRequest) (PublishDecision, error)
	// Published runs inside the publish transaction once the version is
	// live, so an approval it relied on can be marked as used.
	Published(ctx context.Context, q *store.Queries, req PublishRequest, version int) error
}

PublishGate decides whether a person may publish (or roll back to) a template version now. The approvals domain implements it with the optional rule "Publishing a transactional template needs approval"; a nil gate means no approval is needed.

type PublishRequest

type PublishRequest struct {
	WorkspaceID uuid.UUID
	TemplateID  uuid.UUID
	TemplateKey string
	// Version is the version that becomes live: the next one for a publish,
	// an older one for a rollback.
	Version int
	// Rollback is true for "Publish again" and Undo.
	Rollback bool
	// DraftHash fingerprints the draft being published (content, variables,
	// sender and tracking); an approval covers one hash.
	DraftHash string
	Principal *authz.Principal
}

PublishRequest is what a gate decides on.

type RawAttachment

type RawAttachment struct {
	Filename    string
	ContentType string
	ContentID   string
	Content     []byte
}

RawAttachment is a file of a message that arrived by SMTP.

type RawMessage

type RawMessage struct {
	From    mail.Address
	ReplyTo *mail.Address
	// Recipients are the envelope's (RCPT TO): each gets its own message.
	Recipients  []string
	Subject     string
	HTML, Text  string
	Attachments []RawAttachment
	// Tags and Category come from X-ReputeCast-Tags and
	// X-ReputeCast-Category (a category's name or ID).
	Tags     []string
	Category string
	IP       *netip.Addr
}

RawMessage is a message that arrived through the SMTP relay.

type RawResult

type RawResult struct {
	Recipient string
	ID        string
	// Status: queued, rejected (suppressed or opted out) or not_delivered
	// (a test-mode credential's message to an address that isn't allowed).
	Status string
	Detail string
}

RawResult is what happened to one recipient.

type RetentionArgs

type RetentionArgs struct{}

RetentionArgs runs a retention pass.

func (RetentionArgs) InsertOpts

func (RetentionArgs) InsertOpts() river.InsertOpts

InsertOpts implements river.JobArgsWithInsertOpts.

func (RetentionArgs) Kind

func (RetentionArgs) Kind() string

Kind implements river.JobArgs.

type RetentionResult

type RetentionResult struct {
	Content, Messages, Idempotency, RejectedCalls int64
}

RetentionResult is what one retention pass removed.

type RetentionWorker

type RetentionWorker struct {
	river.WorkerDefaults[RetentionArgs]
	S *Service
}

RetentionWorker runs RetentionArgs.

func (*RetentionWorker) Timeout

Timeout bounds one pass.

func (*RetentionWorker) Work

Work implements river.Worker.

type SMTPCredential

type SMTPCredential struct {
	Key       store.TxnKeyRow
	Workspace store.Workspace
}

SMTPCredential is an authenticated SMTP credential.

type Service

type Service struct {
	Pool  *pgxpool.Pool
	Q     *store.Queries
	Audit *audit.Logger
	Box   *secrets.Box
	Links *linktoken.Signer
	URLs  publicurl.Builder
	Log   *slog.Logger
	Jobs  func() *jobs.Client
	// Mailbox classifies a recipient's company domain from its MX records
	// (internal/mailbox), so routing conditions on the mailbox provider see
	// Google Workspace as Gmail; nil uses the domain name only.
	Mailbox MailboxClassifier
	// Checker runs the composer's content checks (links are not probed in
	// the editor).
	Checker *contentcheck.Checker
	// Gate decides whether publishing needs an approval (nil: never).
	Gate PublishGate
	// Accessibility adds the Accessibility group to the checks (nil: none).
	Accessibility AccessibilityChecker
	// Translations are the templates' language versions (nil: every
	// template is in one language).
	Translations Translations
	// Mail sends system mail (alert emails go through notify instead).
	Mail func() mailer.Sender
	// Outbox wakes the sending engine's transactional outbox in the
	// transaction that queued messages.
	Outbox func(ctx context.Context, tx pgx.Tx) error
	Now    func() time.Time
	// contains filtered or unexported fields
}

Service holds the transactional domain's dependencies.

func (*Service) ApplyEvent

func (s *Service) ApplyEvent(ctx context.Context, tx pgx.Tx, p store.Provider, msgID uuid.UUID, stream string, ev providers.Event) error

ApplyEvent is the webhook ingest's hook for provider events of transactional messages: it emits the message.* webhook event, records a soft bounce as the message's final Bounced status, and suppresses an address after SoftBounceLimit soft bounces in a week.

func (*Service) Archive

func (s *Service) Archive(ctx context.Context, ws *store.Workspace, p *authz.Principal, ref string, archive bool) (TransactionalTemplate, error)

Archive takes a template out of use: the API answers template_not_found for it until it is restored.

func (*Service) AuthenticateSMTP

func (s *Service) AuthenticateSMTP(ctx context.Context, username, password string, ip *netip.Addr) (SMTPCredential, error)

AuthenticateSMTP checks an SMTP credential: the username is the key's ID and the password its secret.

func (*Service) Categories

Categories lists the workspace's categories.

func (*Service) CheckAlerts

func (s *Service) CheckAlerts(ctx context.Context) error

CheckAlerts opens and ends the delivery alerts of every workspace that sent transactional mail in the last hour.

func (*Service) ContactActivity

func (s *Service) ContactActivity(ctx context.Context, ws *store.Workspace, contactID uuid.UUID) (TransactionalContactActivity, error)

ContactActivity lists a contact's transactional mail and opt-outs.

func (*Service) Content

Content returns a message's rendered content; every view is audited, because content can hold personal data.

func (*Service) CreateCategory

CreateCategory adds a category.

func (*Service) CreateTemplate

CreateTemplate creates a draft template.

func (*Service) DeleteCategory

func (s *Service) DeleteCategory(ctx context.Context, ws *store.Workspace, p *authz.Principal, id uuid.UUID) error

DeleteCategory removes a category without templates.

func (*Service) DeleteTemplate

func (s *Service) DeleteTemplate(ctx context.Context, ws *store.Workspace, p *authz.Principal, ref string) error

DeleteTemplate removes a template; its messages stay in the log.

func (*Service) Engagement

func (s *Service) Engagement(ctx context.Context, tx pgx.Tx, msgID uuid.UUID, click bool, at time.Time) error

Engagement is the tracking endpoints' hook: the first open or click of a tracked transactional message fires message.opened or message.clicked.

func (*Service) Export

func (s *Service) Export(ctx context.Context, ws *store.Workspace, f LogFilter) ([]byte, int, error)

Export writes the filtered log as CSV (up to ExportMax rows). It needs transactional:content, because it holds addresses, and is audited.

func (*Service) MarkAlertSeen

func (s *Service) MarkAlertSeen(ctx context.Context, ws *store.Workspace, p *authz.Principal, id uuid.UUID) error

MarkAlertSeen hides an open alert from the overview's banner.

func (*Service) Message

Message returns the message detail.

func (*Service) MessageLog

func (s *Service) MessageLog(ctx context.Context, ws *store.Workspace, f LogFilter) (TransactionalLog, error)

MessageLog lists the message log.

func (*Service) NotificationMessage

func (s *Service) NotificationMessage(ctx context.Context, ws *store.Workspace, messageID uuid.UUID) (NotificationMessage, bool, error)

NotificationMessage looks up the transactional message of a link; ok is false for any other mail.

func (*Service) Notifications

func (s *Service) Notifications(ctx context.Context, ws *store.Workspace, email string) (NotificationSet, error)

Notifications lists the workspace's Optional categories and whether an address gets each.

func (*Service) OpenPayload

func (s *Service) OpenPayload(_ context.Context, id uuid.UUID, sealed []byte) (providers.Message, providers.MessageExtras, error)

OpenPayload decodes a queued message for the sending engine's transactional outbox.

func (*Service) OptOutReason

func (s *Service) OptOutReason(ctx context.Context, ws *store.Workspace, email string, category uuid.UUID, reason string) error

OptOutReason keeps the answer to "Why did you turn it off?".

func (*Service) Outcome

func (s *Service) Outcome(ctx context.Context, tx pgx.Tx, wsID uuid.UUID, sent []uuid.UUID, failed map[uuid.UUID]string, at time.Time) error

Outcome is told what the sending engine's transactional outbox did, in the transaction that recorded it: message.sent for messages a provider accepted, message.failed for those every provider failed.

func (*Service) Overview

func (s *Service) Overview(ctx context.Context, ws *store.Workspace, p *authz.Principal, period string, includeTest bool) (TransactionalOverview, error)

Overview returns the Templates tab's header and side cards.

func (*Service) Preview

Preview renders a template version for the editor (nothing is sent).

func (*Service) Publish

Publish makes the draft the live version.

func (*Service) PublishPreview

PublishPreview builds the publish dialog.

func (*Service) Render

Render renders a template's live version with a call's data, as the API would send it (nothing is sent or logged).

func (*Service) Resend

Resend sends a message again with the same data and a new message ID. People only; audited.

func (*Service) Retain

func (s *Service) Retain(ctx context.Context) (RetentionResult, error)

Retain removes what is past its retention.

func (*Service) Rollback

Rollback makes an older version live again ("Publish again", Undo).

func (*Service) SaveDraft

SaveDraft stores a new draft revision.

func (*Service) SaveDraftIn

SaveDraftIn saves the draft, or one of its language versions.

func (*Service) SaveSettings

SaveSettings changes Settings › Transactional.

func (*Service) Send

func (s *Service) Send(ctx context.Context, ws *store.Workspace, in TransactionalSend, idem string, source string) (int, json.RawMessage, error)

Send sends one message (POST …/transactional/messages).

func (*Service) SendBatch

func (s *Service) SendBatch(ctx context.Context, ws *store.Workspace, in TransactionalBatch, idem string) (json.RawMessage, error)

SendBatch sends a batch.

func (*Service) SendRaw

func (s *Service) SendRaw(ctx context.Context, cred SMTPCredential, m RawMessage) ([]RawResult, error)

SendRaw queues a message that arrived by SMTP, one per recipient. An error stops the whole message (the SMTP reply says why); a recipient who is suppressed or opted out is logged as rejected, as with the API.

func (*Service) SetNotifications

func (s *Service) SetNotifications(ctx context.Context, tx pgx.Tx, ws *store.Workspace, email string, on, shown []uuid.UUID, source string, messageID *uuid.UUID) error

SetNotifications saves the preference center's section: of the categories the page showed, those in on are on and the rest off.

func (*Service) Settings

Settings returns Settings › Transactional.

func (*Service) Setup

Setup returns the Setup tab.

func (*Service) Starters

Starters lists the starter templates in the member's language, with the workspace's product name filled in.

func (*Service) Template

Template loads a template for the editor.

func (*Service) TemplateChecks

TemplateChecks runs the checks on a template's draft, or on the editor's unsaved content.

func (*Service) TemplateIn

func (s *Service) TemplateIn(ctx context.Context, ws *store.Workspace, p *authz.Principal, ref, lang string) (TransactionalTemplate, error)

TemplateIn loads a template for the editor in one of its languages: a language version's subject, preheader, content and save state in place of the draft's (?language=).

func (*Service) Templates

func (s *Service) Templates(ctx context.Context, ws *store.Workspace, p *authz.Principal, period string, includeTest bool) (TransactionalTemplateList, error)

Templates lists the templates with their numbers over a period.

func (s *Service) TrackedLink(ctx context.Context, q *store.Queries, msgID uuid.UUID, pos int) (string, bool)

TrackedLink returns a transactional message's tracked link at a position (1-based), for the click redirect.

func (*Service) TurnOff

func (s *Service) TurnOff(ctx context.Context, tx pgx.Tx, ws *store.Workspace, email string, category uuid.UUID, source string, messageID uuid.UUID) error

TurnOff turns one Optional category off for an address (its unsubscribe link, one-click). Turning off an Essential category does nothing.

func (*Service) TurnOn

func (s *Service) TurnOn(ctx context.Context, tx pgx.Tx, ws *store.Workspace, email string, category uuid.UUID) error

TurnOn turns a category back on for an address.

func (*Service) UpdateCategory

UpdateCategory changes a category; its kind can't change while it has templates.

func (*Service) UpdateTemplate

UpdateTemplate applies a TransactionalTemplateUpdate.

func (*Service) Version

func (s *Service) Version(ctx context.Context, ws *store.Workspace, ref string, version int) (TransactionalVersionDetail, error)

Version returns one published version with its content.

func (*Service) Versions

Versions lists a template's published versions.

type TemplatePath

type TemplatePath struct {
	api.WorkspaceInput
	Template string `path:"template" maxLength:"64" doc:"The template's ID, such as password-reset, or its UUID" example:"password-reset"`
}

TemplatePath names a template by its ID (password-reset) or its UUID.

type TransactionalAccess

type TransactionalAccess struct {
	Edit       bool `json:"edit"`
	Publish    bool `json:"publish"`
	Send       bool `json:"send"`
	Content    bool `json:"content"`
	ManageKeys bool `json:"manageKeys"`
	EditRoute  bool `json:"editRoute"`
}

TransactionalAccess is what the person can do from the overview.

type TransactionalAddress

type TransactionalAddress struct {
	Email string `json:"email" maxLength:"254" example:"sam.rivera@outlook.com"`
	Name  string `json:"name,omitempty" maxLength:"200" example:"Sam Rivera"`
}

TransactionalAddress is a recipient: an email and an optional name.

type TransactionalAlert

type TransactionalAlert struct {
	ID        string            `json:"id"`
	Kind      string            `json:"kind" enum:"bounce_rate,failed,median_delivery,failover"`
	Template  *TransactionalRef `json:"template,omitempty" doc:"id is the template's ID (password-reset)"`
	Provider  *TransactionalRef `json:"provider,omitempty" doc:"The provider messages failed over from"`
	Value     float64           `json:"value" doc:"bounce rate %, failed messages, median seconds or failed-over messages"`
	Threshold float64           `json:"threshold"`
	StartedAt time.Time         `json:"startedAt"`
	EndedAt   *time.Time        `json:"endedAt,omitempty"`
	SeenAt    *time.Time        `json:"seenAt,omitempty"`
	Sent      int64             `json:"sent,omitempty"`
	Bounced   int64             `json:"bounced,omitempty"`
	Hard      int64             `json:"hard,omitempty"`
	Domains   []alertDomain     `json:"domains,omitempty"`
	Messages  int64             `json:"messages,omitempty"`
	Lost      int64             `json:"lost,omitempty"`
	Fallback  string            `json:"fallback,omitempty"`
	MedianMs  int64             `json:"medianMs,omitempty"`
}

TransactionalAlert is an open delivery alert or a past incident.

type TransactionalAttachmentInput

type TransactionalAttachmentInput struct {
	Filename    string `json:"filename" minLength:"1" maxLength:"255" example:"INV-2026-0418.pdf"`
	ContentType string `json:"content_type,omitempty" maxLength:"200" example:"application/pdf" doc:"Guessed from the file name when omitted"`
	Content     string `json:"content" doc:"The file, base64-encoded"`
	ContentID   string `json:"content_id,omitempty" maxLength:"200" doc:"Makes it an inline image the HTML references as cid:<content_id>"`
}

TransactionalAttachmentInput is a file sent with a message.

type TransactionalAttachmentMeta

type TransactionalAttachmentMeta struct {
	Filename    string `json:"filename"`
	ContentType string `json:"contentType"`
	Size        int    `json:"size"`
	ContentID   string `json:"contentId,omitempty"`
}

TransactionalAttachmentMeta describes a file sent with a message (files aren't stored).

type TransactionalAttempt

type TransactionalAttempt struct {
	Provider  string    `json:"provider"`
	At        time.Time `json:"at"`
	OK        bool      `json:"ok"`
	Error     string    `json:"error,omitempty"`
	Temporary bool      `json:"temporary,omitempty"`
	GaveUp    bool      `json:"gaveUp,omitempty"`
	Down      bool      `json:"down,omitempty"`
}

TransactionalAttempt is one provider call for a message.

type TransactionalBatch

type TransactionalBatch struct {
	Messages []TransactionalSend `json:"messages" minItems:"1" maxItems:"100"`
}

TransactionalBatch sends up to 100 messages, each with its own recipient and data.

type TransactionalBatchItem

type TransactionalBatchItem struct {
	Index  int        `json:"index"`
	ID     string     `json:"id,omitempty"`
	Status string     `json:"status" enum:"queued,scheduled,not_delivered,error"`
	SendAt *time.Time `json:"send_at,omitempty"`
	Test   bool       `json:"test,omitempty"`
	// Error is the problem that stopped this message (same codes as one send).
	Error *Problem `json:"error,omitempty"`
}

TransactionalBatchItem is one message's answer in a batch.

type TransactionalBatchResult

type TransactionalBatchResult struct {
	Results  []TransactionalBatchItem `json:"results"`
	Accepted int                      `json:"accepted"`
	Failed   int                      `json:"failed"`
}

TransactionalBatchResult answers a batch: each message gets its own answer.

type TransactionalBounce

type TransactionalBounce struct {
	Kind       string `json:"kind" enum:"hard,soft"`
	Class      string `` /* 130-byte string literal not displayed */
	Diagnostic string `json:"diagnostic,omitempty" example:"452 4.2.2 mailbox full"`
}

TransactionalBounce is a bounced message's last bounce.

type TransactionalBreakingChange

type TransactionalBreakingChange struct {
	Calls int `json:"calls" doc:"Calls to the template in the last 7 days"`
	// Breaking lists required variables recent calls didn't send.
	Breaking []TransactionalBreakingVariable `json:"breaking"`
	// Unused lists variables recent calls send that the draft no longer declares.
	Unused []string `json:"unused"`
	// Summary is the dialog's sentence, empty when nothing breaks.
	Summary string `json:"summary"`
}

TransactionalBreakingChange compares the draft with the requests of the last 7 days.

type TransactionalBreakingVariable

type TransactionalBreakingVariable struct {
	Name string `json:"name"`
	// Calls is how many of the recent calls didn't send it.
	CallsWithout     int    `json:"callsWithout"`
	Type             string `json:"type"`
	SuggestedDefault string `json:"suggestedDefault"`
}

TransactionalBreakingVariable is a variable that would make recent calls fail.

type TransactionalCategory

type TransactionalCategory struct {
	ID          string `json:"id"`
	Name        string `json:"name"`
	Kind        string `json:"kind" enum:"essential,optional"`
	Description string `json:"description" doc:"What recipients see in the preference center"`
	Templates   int64  `json:"templates"`
	OptedOut    int64  `json:"optedOut"`
}

TransactionalCategory groups templates. Essential categories are always sent; recipients can turn Optional ones off.

type TransactionalCategoryInput

type TransactionalCategoryInput struct {
	Name        string `json:"name" minLength:"1" maxLength:"60"`
	Kind        string `json:"kind" enum:"essential,optional"`
	Description string `json:"description,omitempty" maxLength:"200"`
}

TransactionalCategoryInput creates or changes a category.

type TransactionalCategoryList

type TransactionalCategoryList struct {
	Items []TransactionalCategory `json:"items"`
	// CanEdit is transactional:publish; Reason explains a read-only card.
	CanEdit bool   `json:"canEdit"`
	Reason  string `json:"reason,omitempty"`
}

TransactionalCategoryList is the Categories card.

type TransactionalCategoryRef

type TransactionalCategoryRef struct {
	ID   string `json:"id"`
	Name string `json:"name"`
	Kind string `json:"kind" enum:"essential,optional"`
}

TransactionalCategoryRef names a template's category.

type TransactionalCheck

type TransactionalCheck struct {
	ID       string                  `json:"id" example:"variables.undeclared"`
	Severity string                  `json:"severity" enum:"block,warn,info,pass"`
	Group    string                  `json:"group" enum:"Content,Links,Compliance,Subject,Variables,Test data,Privacy,Accessibility"`
	Title    string                  `json:"title"`
	Detail   string                  `json:"detail,omitempty"`
	Where    string                  `json:"where,omitempty" enum:"subject,preheader,body,text"`
	Line     int                     `json:"line,omitempty"`
	Variable string                  `json:"variable,omitempty"`
	TestData string                  `json:"testData,omitempty"`
	Path     []int                   `json:"path"`
	Fixes    []TransactionalCheckFix `json:"fixes"`
}

TransactionalCheck is one finding of a template's checks: the composer's content checks plus the transactional ones (Liquid errors, undeclared and unused variables, test data that fails to render, a sensitive variable in the subject, tracking on an Essential template).

type TransactionalCheckFix

type TransactionalCheckFix struct {
	Kind  string `` /* 163-byte string literal not displayed */
	Label string `json:"label"`
	Value string `json:"value,omitempty"`
	// Variable and TestData say what the fix is about.
	Variable string `json:"variable,omitempty"`
	TestData string `json:"testData,omitempty"`
	Path     []int  `json:"path,omitempty"`
}

TransactionalCheckFix is a one-click fix offered with a finding.

type TransactionalChecks

type TransactionalChecks struct {
	Verdict   string                      `json:"verdict" enum:"ready,warnings,blocked"`
	Blocks    int                         `json:"blocks"`
	Warnings  int                         `json:"warnings"`
	Passed    int                         `json:"passed"`
	SizeBytes int                         `json:"sizeBytes"`
	ClipBytes int                         `json:"clipBytes"`
	Links     int                         `json:"links"`
	Images    int                         `json:"images"`
	Checks    []TransactionalCheck        `json:"checks"`
	Variables TransactionalVariableReport `json:"variables"`
	TestData  []TransactionalTestRender   `json:"testData"`
	PlainText string                      `json:"plainText"`
}

TransactionalChecks is the Checks tab and the publish dialog's summary.

type TransactionalChecksInput

type TransactionalChecksInput struct {
	Subject     *string                  `json:"subject,omitempty" maxLength:"998"`
	Preheader   *string                  `json:"preheader,omitempty" maxLength:"500"`
	EditorMode  *string                  `json:"editorMode,omitempty" enum:"visual,mjml,html"`
	MJML        *string                  `json:"mjml,omitempty" maxLength:"2000000"`
	HTML        *string                  `json:"html,omitempty" maxLength:"2500000"`
	PlainText   *string                  `json:"plainText,omitempty" maxLength:"500000"`
	Variables   *[]TransactionalVariable `json:"variables,omitempty" maxItems:"200"`
	TestData    *[]TransactionalTestData `json:"testData,omitempty" maxItems:"50"`
	TrackOpens  *bool                    `json:"trackOpens,omitempty"`
	TrackClicks *bool                    `json:"trackClicks,omitempty"`
}

TransactionalChecksInput runs the checks on the editor's current, unsaved content; omitted fields use the saved draft.

type TransactionalContactActivity

type TransactionalContactActivity struct {
	Messages []TransactionalContactMessage `json:"messages"`
	// OptOuts are the Optional categories the address turned off.
	OptOuts []TransactionalContactOptOut `json:"optOuts"`
	// Categories are every Optional category with whether it is on.
	Categories []TransactionalContactCategory `json:"categories"`
	// CanViewContent: the message content needs transactional:content.
	CanViewContent bool `json:"canViewContent"`
}

TransactionalContactActivity is a contact's transactional mail.

type TransactionalContactCategory

type TransactionalContactCategory struct {
	ID   string `json:"id"`
	Name string `json:"name"`
	On   bool   `json:"on"`
}

TransactionalContactCategory is an Optional category for an address.

type TransactionalContactMessage

type TransactionalContactMessage struct {
	ID       string                    `json:"id"`
	At       time.Time                 `json:"at"`
	Template *TransactionalLogTemplate `json:"template,omitempty"`
	Raw      bool                      `json:"raw"`
	Subject  string                    `json:"subject"`
	Status   string                    `json:"status" enum:"queued,sent,delivered,deferred,bounced,complained,rejected,failed,test"`
	Provider string                    `json:"provider,omitempty"`
	Category string                    `json:"category,omitempty"`
	// DeliveryMs: from the call to the delivery event, once delivered.
	DeliveryMs *int64 `json:"deliveryMs,omitempty"`
}

TransactionalContactMessage is one message in a contact's timeline.

type TransactionalContactOptOut

type TransactionalContactOptOut struct {
	CategoryID string    `json:"categoryId"`
	Category   string    `json:"category"`
	Since      time.Time `json:"since"`
	Source     string    `json:"source"`
	Reason     string    `json:"reason,omitempty"`
}

TransactionalContactOptOut is an Optional category an address turned off.

type TransactionalContent

type TransactionalContent struct {
	HTML      string                    `json:"html"`
	Text      string                    `json:"text"`
	Headers   []TransactionalHeaderPair `json:"headers"`
	ExpiresAt time.Time                 `json:"expiresAt"`
	Masked    []string                  `json:"masked"`
}

TransactionalContent is a message's rendered content, as stored: sensitive values are ••••••.

type TransactionalContentState

type TransactionalContentState struct {
	Available bool       `json:"available"`
	ExpiresAt *time.Time `json:"expiresAt,omitempty"`
	RemovedAt *time.Time `json:"removedAt,omitempty"`
	// CanView: viewing content needs transactional:content (and is
	// audited); Helpers can grant it.
	CanView       bool      `json:"canView"`
	Helpers       []string  `json:"helpers"`
	RetentionDays int       `json:"retentionDays"`
	MetadataUntil time.Time `json:"metadataUntil"`
	// Masked names the sensitive variables shown as ••••••.
	Masked []string `json:"masked"`
}

TransactionalContentState says whether the rendered content can be shown.

type TransactionalDiff

type TransactionalDiff struct {
	Subject   *TransactionalTextChange      `json:"subject,omitempty"`
	Preheader *TransactionalTextChange      `json:"preheader,omitempty"`
	Variables []TransactionalVariableChange `json:"variables"`
	// ContentSummary is "2 text blocks changed · button “Upgrade now” is
	// now “Choose a plan”"; Content is the full text diff.
	ContentSummary string                  `json:"contentSummary"`
	Content        []TransactionalDiffLine `json:"content"`
	// Settings lists other changes (sender, reply-to, tracking).
	Settings []string `json:"settings"`
	Changed  bool     `json:"changed"`

	// Languages are the language versions added, changed or removed.
	Languages []TransactionalLanguageChange `json:"languages,omitempty"`
	// contains filtered or unexported fields
}

TransactionalDiff is what changes when the draft is published.

type TransactionalDiffLine

type TransactionalDiffLine struct {
	Kind string `json:"kind" enum:"ctx,add,del"`
	Text string `json:"text"`
}

TransactionalDiffLine is one line of a text diff.

type TransactionalDraftSave

type TransactionalDraftSave struct {
	// BaseRevision is the draft revision the editor started from. Saving on
	// top of a teammate's newer save fails with 409 version_conflict
	// unless Force is set.
	BaseRevision int                      `json:"baseRevision" minimum:"1"`
	Subject      *string                  `json:"subject,omitempty" maxLength:"998"`
	Preheader    *string                  `json:"preheader,omitempty" maxLength:"500"`
	EditorMode   *string                  `json:"editorMode,omitempty" enum:"visual,mjml,html"`
	MJML         *string                  `json:"mjml,omitempty" maxLength:"2000000"`
	HTML         *string                  `json:"html,omitempty" maxLength:"2500000" doc:"The HTML the editor compiled; empty compiles the MJML on the server"`
	PlainText    *string                  `json:"plainText,omitempty" maxLength:"500000"`
	Variables    *[]TransactionalVariable `json:"variables,omitempty" maxItems:"200"`
	TestData     *[]TransactionalTestData `json:"testData,omitempty" maxItems:"50"`
	SenderID     *string                  `json:"senderId,omitempty" doc:"A Transactional sender, or empty for the default"`
	ReplyTo      *string                  `json:"replyTo,omitempty" maxLength:"254"`
	TrackOpens   *bool                    `json:"trackOpens,omitempty"`
	TrackClicks  *bool                    `json:"trackClicks,omitempty"`
	Label        string                   `json:"label,omitempty" maxLength:"200"`
	Source       string                   `json:"source,omitempty" enum:"autosave,manual,import,restore" default:"autosave"`
	Force        bool                     `json:"force,omitempty"`
}

TransactionalDraftSave is one save of the editor (autosave). Omitted fields keep their value.

type TransactionalDraftSaved

type TransactionalDraftSaved struct {
	DraftRevision int       `json:"draftRevision"`
	SavedAt       time.Time `json:"savedAt"`
	DraftHash     string    `json:"draftHash"`
	DraftChanges  bool      `json:"draftChanges"`
	SizeBytes     int       `json:"sizeBytes"`
	HTML          string    `json:"html"`
	PlainText     string    `json:"plainText"`
}

TransactionalDraftSaved is the result of a save.

type TransactionalErrorCode

type TransactionalErrorCode struct {
	Code   string `json:"code"`
	Status int    `json:"status"`
}

TransactionalErrorCode is one row of the error table.

type TransactionalFailover

type TransactionalFailover struct {
	From string     `json:"from"`
	To   string     `json:"to"`
	At   *time.Time `json:"at,omitempty"`
}

TransactionalFailover says a message went through the route's fallback.

type TransactionalFailoverState

type TransactionalFailoverState struct {
	From TransactionalRef `json:"from"`
	To   TransactionalRef `json:"to"`
	// Since is when the primary went down; Code its last answer ("503").
	Since    time.Time `json:"since"`
	Code     string    `json:"code,omitempty"`
	Messages int64     `json:"messages"`
	Lost     int64     `json:"lost"`
	MedianMs *int64    `json:"medianMs,omitempty"`
	// Recovering: calls succeed again; the primary takes over after ten
	// healthy minutes.
	Recovering bool `json:"recovering"`
}

TransactionalFailoverState is an outage of the primary: mail goes through the fallback.

type TransactionalFirstRun

type TransactionalFirstRun struct {
	Templates      int64 `json:"templates"`
	Published      int64 `json:"published"`
	Messages       int64 `json:"messages"`
	Keys           int   `json:"keys"`
	Senders        int   `json:"senders" doc:"Senders on Transactional domains"`
	VerifiedSender bool  `json:"verifiedSender"`
}

TransactionalFirstRun is what the first-run state and the guide check.

type TransactionalHeaderPair

type TransactionalHeaderPair struct {
	Name  string `json:"name"`
	Value string `json:"value"`
}

TransactionalHeaderPair is one header.

type TransactionalHour

type TransactionalHour struct {
	Sent       int64   `json:"sent"`
	Bounced    int64   `json:"bounced"`
	BounceRate float64 `json:"bounceRate"`
	MedianMs   *int64  `json:"medianMs,omitempty"`
}

TransactionalHour is the last hour, for the alert banner.

type TransactionalLanguageChange

type TransactionalLanguageChange struct {
	Language string `json:"language"`
	Name     string `json:"name"`
	Change   string `json:"change" enum:"added,changed,removed"`
}

TransactionalLanguageChange is a language version the draft adds, changes or removes since the live version (publishing one is a change).

type TransactionalLimits

type TransactionalLimits struct {
	MaxBatch int `json:"maxBatch"`
	// RatePerSecond is a key's default rate.
	RatePerSecond int `json:"ratePerSecond"`
	// RouteLimitBytes is the largest message the route's providers accept
	// (attachments included); RouteLimitProvider is the smallest's name.
	RouteLimitBytes    int64  `json:"routeLimitBytes"`
	RouteLimitProvider string `json:"routeLimitProvider,omitempty"`
	// RouteLimitOthers are the route's providers that accept more ("SES
	// allows 40 MB"), in route order.
	RouteLimitOthers []TransactionalProviderLimit `json:"routeLimitOthers"`
	IdempotencyHours int                          `json:"idempotencyHours"`
	ScheduleHours    int                          `json:"scheduleHours"`
	SMTPRecipients   int                          `json:"smtpRecipients"`
}

TransactionalLimits are the API's limits.

type TransactionalLog

type TransactionalLog struct {
	Items  []TransactionalLogItem `json:"items"`
	Counts TransactionalLogCounts `json:"counts"`
	// Next pages to older messages; Newest is the cursor of the first item,
	// for live updates (after=Newest returns only newer messages).
	Next    string                  `json:"next,omitempty"`
	Newest  string                  `json:"newest,omitempty"`
	Since   time.Time               `json:"since"`
	Until   time.Time               `json:"until"`
	Filters TransactionalLogFilters `json:"filters"`
	// Retention: metadata and events are kept MetadataDays, rendered
	// content ContentDays.
	MetadataDays int `json:"metadataDays"`
	ContentDays  int `json:"contentDays"`
	// CanExport: exporting needs transactional:content.
	CanExport bool `json:"canExport"`
}

TransactionalLog is a page of the message log.

type TransactionalLogCounts

type TransactionalLogCounts struct {
	All        int64 `json:"all"`
	Queued     int64 `json:"queued"`
	Sent       int64 `json:"sent"`
	Delivered  int64 `json:"delivered"`
	Deferred   int64 `json:"deferred"`
	Bounced    int64 `json:"bounced"`
	Complained int64 `json:"complained"`
	Rejected   int64 `json:"rejected"`
	Failed     int64 `json:"failed"`
	Test       int64 `json:"test"`
}

TransactionalLogCounts are the log's numbers per status.

type TransactionalLogFilters

type TransactionalLogFilters struct {
	Templates []TransactionalRef `json:"templates" doc:"id is the template's ID; raw is mail that arrived by SMTP"`
	Providers []TransactionalRef `json:"providers"`
	Keys      []TransactionalRef `json:"keys"`
}

TransactionalLogFilters are the log's filter choices.

type TransactionalLogItem

type TransactionalLogItem struct {
	ID        string    `json:"id"`
	At        time.Time `json:"at" doc:"When the call was accepted"`
	Email     string    `json:"email"`
	Name      string    `json:"name,omitempty"`
	ContactID string    `json:"contactId,omitempty"`
	// Template is nil for mail that arrived by SMTP (Raw).
	Template *TransactionalLogTemplate `json:"template,omitempty"`
	Raw      bool                      `json:"raw"`
	Subject  string                    `json:"subject"`
	Provider *TransactionalRef         `json:"provider,omitempty"`
	Status   string                    `json:"status" enum:"queued,sent,delivered,deferred,bounced,complained,rejected,failed,test"`
	// DeliveryMs is how long after the call it was delivered.
	DeliveryMs    *int64                  `json:"deliveryMs,omitempty"`
	Deferrals     int                     `json:"deferrals"`
	Bounce        *TransactionalBounce    `json:"bounce,omitempty"`
	Rejection     *TransactionalRejection `json:"rejection,omitempty"`
	TestDelivered bool                    `json:"testDelivered"`
	FailedOver    *TransactionalFailover  `json:"failedOver,omitempty"`
	// RoleAddress: its marketing-only role suppression doesn't apply.
	RoleAddress bool       `json:"roleAddress"`
	Tracked     bool       `json:"tracked"`
	OpenedAt    *time.Time `json:"openedAt,omitempty"`
	ClickedAt   *time.Time `json:"clickedAt,omitempty"`
	Error       string     `json:"error,omitempty"`
	Key         string     `json:"key,omitempty"`
	Category    string     `json:"category,omitempty"`
	// Language is the language version the message went out in (a base
	// code such as es); empty for a template in one language.
	Language string `json:"language,omitempty"`
}

TransactionalLogItem is one message in the log.

type TransactionalLogTemplate

type TransactionalLogTemplate struct {
	Key     string `json:"key"`
	Name    string `json:"name"`
	Version *int32 `json:"version,omitempty"`
}

TransactionalLogTemplate is a message's template and version.

type TransactionalMakeOptional

type TransactionalMakeOptional struct {
	Name    string `json:"name" minLength:"1" maxLength:"64"`
	Default string `json:"default" maxLength:"4000"`
}

TransactionalMakeOptional turns a required variable into an optional one with a default when publishing ("Make trial_end_date optional, with the default “soon”").

type TransactionalMessageDetail

type TransactionalMessageDetail struct {
	TransactionalLogItem
	Contact           *TransactionalRef `json:"contact,omitempty"`
	CategoryKind      string            `json:"categoryKind,omitempty"`
	ProviderMessageID string            `json:"providerMessageId,omitempty"`
	KeyRef            *TransactionalRef `json:"keyRef,omitempty"`
	IP                string            `json:"ip,omitempty"`
	IdempotencyKey    string            `json:"idempotencyKey,omitempty"`
	Tags              []string          `json:"tags"`
	Metadata          map[string]string `json:"metadata"`
	From              string            `json:"from"`
	ReplyTo           string            `json:"replyTo,omitempty"`
	Cc                []string          `json:"cc"`
	Bcc               []string          `json:"bcc"`
	// Dropped are copies left out because the address is suppressed.
	Dropped     []string                      `json:"dropped"`
	Attachments []TransactionalAttachmentMeta `json:"attachments"`
	// ContentBytes is the HTML and text; SizeBytes adds the attachments.
	ContentBytes int `json:"contentBytes"`
	SizeBytes    int `json:"sizeBytes"`
	Variables    int `json:"variables"`
	// SensitiveSent are the sensitive variables the call sent.
	SensitiveSent []string `json:"sensitiveSent"`
	// Source: api, batch, smtp, resend, guide or test; SentBy is the person
	// for resend, guide and test sends.
	Source     string                         `json:"source"`
	SentBy     string                         `json:"sentBy,omitempty"`
	ResentFrom string                         `json:"resentFrom,omitempty"`
	SendAt     *time.Time                     `json:"sendAt,omitempty"`
	Route      TransactionalRouteInfo         `json:"route"`
	Timeline   []TransactionalTimelineEntry   `json:"timeline"`
	Attempts   []TransactionalAttempt         `json:"attempts"`
	Request    TransactionalRequest           `json:"request"`
	Webhooks   []TransactionalWebhookDelivery `json:"webhooks"`
	// Suppression is the address's suppression as it is now (bounced
	// messages: added by this bounce).
	Suppression *TransactionalSuppressionInfo `json:"suppression,omitempty"`
	// SoftBounces counts the address's soft bounces in 7 days (limit 3).
	SoftBounces     *int                      `json:"softBounces,omitempty"`
	SoftBounceLimit int                       `json:"softBounceLimit"`
	Content         TransactionalContentState `json:"content"`
	Resend          TransactionalResendState  `json:"resend"`
	// CanRemoveSuppression: removing needs subscribers:edit.
	CanRemoveSuppression bool `json:"canRemoveSuppression"`
	// Language: the version sent and why; nil for a template in one language.
	Language *TransactionalMessageLanguage `json:"languageInfo,omitempty"`
}

TransactionalMessageDetail is the message detail panel.

type TransactionalMessageEvent

type TransactionalMessageEvent struct {
	MessageID         string            `json:"message_id"`
	Template          string            `json:"template"`
	TemplateVersion   *int32            `json:"template_version,omitempty"`
	Category          string            `json:"category,omitempty"`
	To                string            `json:"to"`
	Status            string            `json:"status"`
	Reason            string            `json:"reason,omitempty"`
	Provider          string            `json:"provider,omitempty"`
	ProviderMessageID string            `json:"provider_message_id,omitempty"`
	Tags              []string          `json:"tags"`
	Metadata          map[string]string `json:"metadata"`
	Test              bool              `json:"test,omitempty"`
	At                time.Time         `json:"at"`
}

TransactionalMessageEvent is the data of a message.* webhook event.

type TransactionalMessageLanguage

type TransactionalMessageLanguage struct {
	// Sent is the version's language; Contact the contact's language, or
	// the one the call asked for.
	Sent    string `json:"sent"`
	Contact string `json:"contact,omitempty"`
	Reason  string `json:"reason,omitempty" enum:"match,no_language,not_offered,missing,draft,held,requested,"`
}

TransactionalMessageLanguage is why a message went out in its language: "Spanish, from the contact", "Requested pt-BR, sent English".

type TransactionalOptOutInfo

type TransactionalOptOutInfo struct {
	Category string    `json:"category"`
	Since    time.Time `json:"since"`
	Source   string    `json:"source" enum:"preference_center,unsubscribe_link,one_click,api,member,"`
}

TransactionalOptOutInfo is the opt-out that stopped a message.

type TransactionalOverview

type TransactionalOverview struct {
	Period      string                      `json:"period" enum:"24h,7d,30d"`
	IncludeTest bool                        `json:"includeTest"`
	Stats       TransactionalOverviewStats  `json:"stats"`
	Route       TransactionalRouteSummary   `json:"route"`
	Failover    *TransactionalFailoverState `json:"failover,omitempty"`
	// Alerts are the open delivery alerts (failovers are in Failover).
	Alerts []TransactionalAlert `json:"alerts"`
	// Incidents are the alerts and failovers of the last 30 days.
	Incidents []TransactionalAlert      `json:"incidents"`
	Hour      TransactionalHour         `json:"hour"`
	Keys      []TransactionalSendingKey `json:"keys"`
	FirstRun  TransactionalFirstRun     `json:"firstRun"`
	// Endpoint is the send API's URL on this instance.
	Endpoint string              `json:"endpoint"`
	Can      TransactionalAccess `json:"can"`
}

TransactionalOverview is the Templates tab's header and side cards.

type TransactionalOverviewStats

type TransactionalOverviewStats struct {
	TransactionalStats
	Suppressed int64 `json:"suppressed"`
	OptedOut   int64 `json:"optedOut"`
	// Keys is how many API keys called in the period, test-mode keys
	// included; SMTP whether the relay sent.
	Keys int64 `json:"keys"`
	SMTP bool  `json:"smtp"`
	// ComplainedOn names the templates with complaints.
	ComplainedOn []string `json:"complainedOn"`
}

TransactionalOverviewStats are the workspace's numbers over a period.

type TransactionalPreview

type TransactionalPreview struct {
	Version   string `json:"version"`
	Subject   string `json:"subject"`
	Preheader string `json:"preheader"`
	HTML      string `json:"html"`
	Text      string `json:"text"`
	FromName  string `json:"fromName"`
	FromEmail string `json:"fromEmail"`
	ReplyTo   string `json:"replyTo"`
	SizeBytes int    `json:"sizeBytes"`
	// OK is false when the data lacks a required variable or Liquid fails;
	// Missing and Problem say why.
	OK       bool     `json:"ok"`
	Missing  []string `json:"missing"`
	Defaults []string `json:"defaults"`
	Problem  string   `json:"problem,omitempty"`
}

TransactionalPreview is a rendered template.

type TransactionalPreviewInput

type TransactionalPreviewInput struct {
	Version  string                `json:"version,omitempty" doc:"draft (default), live, or a version number" example:"draft"`
	TestData string                `json:"testData,omitempty" maxLength:"80" doc:"The name of a test data set"`
	Data     map[string]any        `json:"data,omitempty" doc:"Data to render with instead of a test data set"`
	To       *TransactionalAddress `json:"to,omitempty"`
	// Unsaved editor content (draft only).
	Subject   *string                  `json:"subject,omitempty" maxLength:"998"`
	Preheader *string                  `json:"preheader,omitempty" maxLength:"500"`
	MJML      *string                  `json:"mjml,omitempty" maxLength:"2000000"`
	HTML      *string                  `json:"html,omitempty" maxLength:"2500000"`
	PlainText *string                  `json:"plainText,omitempty" maxLength:"500000"`
	Variables *[]TransactionalVariable `json:"variables,omitempty" maxItems:"200"`
}

TransactionalPreviewInput renders a template in the editor: its draft (default), its live version or a published version, with a test data set or data of your own. Content fields preview unsaved changes.

type TransactionalProviderLimit

type TransactionalProviderLimit struct {
	Provider string `json:"provider" example:"SES"`
	Bytes    int64  `json:"bytes"`
}

TransactionalProviderLimit is the largest message one provider accepts.

type TransactionalPublishApproval

type TransactionalPublishApproval struct {
	Required  bool     `json:"required"`
	Approvers []string `json:"approvers"`
	Reason    string   `json:"reason,omitempty"`
}

TransactionalPublishApproval says whether the workspace's approval rule applies.

type TransactionalPublishInput

type TransactionalPublishInput struct {
	// BaseRevision is the draft revision the person reviewed; a newer save
	// since then answers 409 version_conflict.
	BaseRevision int    `json:"baseRevision" minimum:"1"`
	Note         string `json:"note,omitempty" maxLength:"300" doc:"Shown in the version history instead of the generated summary"`
	// MakeOptional applies the dialog's recommended fix before publishing.
	MakeOptional []TransactionalMakeOptional `json:"makeOptional,omitempty" maxItems:"50"`
	// PublishAnyway publishes despite a breaking change.
	PublishAnyway bool `json:"publishAnyway,omitempty"`
}

TransactionalPublishInput publishes the draft.

type TransactionalPublishLanguage

type TransactionalPublishLanguage struct {
	Language string `json:"language"`
	Name     string `json:"name"`
	// Status is source, up_to_date, outdated or draft. A draft is
	// published with the others but not sent: its readers get the
	// fallback until it is marked translated.
	Status string `json:"status" enum:"source,up_to_date,outdated,draft"`
	// Attention counts what changed in the source since it was translated.
	Attention int `json:"attention"`
	// Gets is the version its recipients get: itself, or the fallback for
	// a draft; GetsName names it.
	Gets     string `json:"gets"`
	GetsName string `json:"getsName"`
}

TransactionalPublishLanguage is a language version publishing the draft publishes: the publish dialog says "Publishes English, Spanish and German together" and lists any outdated one.

type TransactionalPublishPreview

type TransactionalPublishPreview struct {
	TemplateID    string                       `json:"templateId"`
	Key           string                       `json:"key"`
	Name          string                       `json:"name"`
	Category      *TransactionalCategoryRef    `json:"category,omitempty"`
	NextVersion   int                          `json:"nextVersion"`
	LiveVersion   *int                         `json:"liveVersion,omitempty"`
	LiveSince     *time.Time                   `json:"liveSince,omitempty"`
	LiveBy        string                       `json:"liveBy,omitempty"`
	DraftRevision int                          `json:"draftRevision"`
	DraftSavedAt  time.Time                    `json:"draftSavedAt"`
	DraftSavedBy  string                       `json:"draftSavedBy"`
	Diff          TransactionalDiff            `json:"diff"`
	Breaking      TransactionalBreakingChange  `json:"breaking"`
	TestRenders   []TransactionalTestRender    `json:"testRenders"`
	Checks        TransactionalChecks          `json:"checks"`
	Approval      TransactionalPublishApproval `json:"approval"`
	// Blocking lists why the draft can't be published (Liquid errors, test
	// data that doesn't render); empty when it can.
	Blocking   []string `json:"blocking"`
	CanPublish bool     `json:"canPublish"`
	// Languages are the language versions published with it, the source
	// first (empty for a template in one language).
	Languages []TransactionalPublishLanguage `json:"languages"`
}

TransactionalPublishPreview is everything the publish dialog shows.

type TransactionalPublishPreviewInput

type TransactionalPublishPreviewInput struct {
	MakeOptional []TransactionalMakeOptional `json:"makeOptional,omitempty" maxItems:"50"`
}

TransactionalPublishPreviewInput recomputes the dialog with a fix applied.

type TransactionalPublished

type TransactionalPublished struct {
	Version  int                   `json:"version"`
	Previous *int                  `json:"previous,omitempty" doc:"The version that was live before (Undo publishes it again)"`
	Template TransactionalTemplate `json:"template"`
}

TransactionalPublished is the result of publishing or rolling back.

type TransactionalRef

type TransactionalRef struct {
	ID   string `json:"id"`
	Name string `json:"name"`
}

TransactionalRef names something.

type TransactionalRejection

type TransactionalRejection struct {
	Reason      string                        `json:"reason" enum:"suppressed,opted_out,test_not_allowed,provider"`
	Suppression *TransactionalSuppressionInfo `json:"suppression,omitempty"`
	OptOut      *TransactionalOptOutInfo      `json:"optOut,omitempty"`
	// Allowed are a test-mode key's allowed addresses (besides members).
	Allowed []string `json:"allowed,omitempty"`
	// Error is the provider's answer when it refused the message.
	Error string `json:"error,omitempty"`
}

TransactionalRejection says why a message stopped before sending.

type TransactionalRelay

type TransactionalRelay struct {
	Enabled      bool   `json:"enabled"`
	Hostname     string `json:"hostname,omitempty"`
	StartTLSPort int    `json:"starttlsPort"`
	TLSPort      int    `json:"tlsPort"`
	// State: off, ok, unreachable, certificate (expired or failing) or
	// unchecked.
	State            string                    `json:"state" enum:"off,ok,unreachable,certificate,unchecked"`
	UnreachableSince *time.Time                `json:"unreachableSince,omitempty"`
	CertNotAfter     *time.Time                `json:"certNotAfter,omitempty"`
	Checks           []TransactionalRelayCheck `json:"checks"`
	EnabledBy        string                    `json:"enabledBy,omitempty"`
	EnabledAt        *time.Time                `json:"enabledAt,omitempty"`
	// Admins are the instance admins who can turn it on.
	Admins []string `json:"admins"`
	// CanManage: the caller is an instance admin.
	CanManage bool `json:"canManage"`
}

TransactionalRelay is the SMTP relay as the instance runs it.

type TransactionalRelayCheck

type TransactionalRelayCheck struct {
	Key    string `json:"key" enum:"dns,starttls,tls,certificate"`
	OK     bool   `json:"ok"`
	Detail string `json:"detail"`
}

TransactionalRelayCheck is one status check of the relay.

type TransactionalRenderInput

type TransactionalRenderInput struct {
	Data map[string]any        `json:"data,omitempty" doc:"The template's variables"`
	To   *TransactionalAddress `json:"to,omitempty" doc:"Fills to.email and to.name"`
	// Language picks a language version, as a send does.
	Language string `` /* 154-byte string literal not displayed */
}

TransactionalRenderInput is the API's render: the live version with the data a call would send.

type TransactionalRendered

type TransactionalRendered struct {
	Template string `json:"template" example:"password-reset"`
	Version  int    `json:"version" example:"3"`
	Subject  string `json:"subject"`
	HTML     string `json:"html"`
	Text     string `json:"text"`
	// Language is the language version rendered.
	Language string `json:"language,omitempty" example:"es"`
}

TransactionalRendered is a rendered live version.

type TransactionalRequest

type TransactionalRequest struct {
	Method         string          `json:"method"`
	Path           string          `json:"path"`
	IdempotencyKey string          `json:"idempotencyKey,omitempty"`
	Body           json.RawMessage `json:"body"`
	// SMTP: mail that arrived through the relay (no JSON body).
	SMTP bool `json:"smtp"`
}

TransactionalRequest is the call that produced a message, as stored: sensitive values are ••••••.

type TransactionalResendState

type TransactionalResendState struct {
	Available bool `json:"available"`
	// Reason when it isn't: sensitive (a sensitive variable wasn't stored),
	// attachments (files weren't stored), raw (SMTP mail), template (the
	// template isn't published any more), permission (needs
	// transactional:send), not_sent (it was never accepted for sending).
	Reason    string   `json:"reason,omitempty" enum:"sensitive,attachments,raw,template,permission,not_sent,"`
	Sensitive []string `json:"sensitive,omitempty"`
}

TransactionalResendState says whether a person can resend the message.

type TransactionalRollbackInput

type TransactionalRollbackInput struct {
	Version int `json:"version" minimum:"1"`
	// Undo marks the rollback as the Undo of a publish (within seconds).
	Undo bool `json:"undo,omitempty"`
}

TransactionalRollbackInput publishes an older version again.

type TransactionalRouteInfo

type TransactionalRouteInfo struct {
	Rule     string `json:"rule"`
	Matched  string `json:"matched,omitempty" doc:"The condition's field: category or mailbox_provider"`
	Value    string `json:"value,omitempty"`
	Primary  string `json:"primary,omitempty"`
	Fallback string `json:"fallback,omitempty"`
	Policy   string `json:"policy,omitempty"`
	// FailedOver: the primary was down when the call came, so the message
	// went to the fallback at once.
	FailedOver bool `json:"failedOver"`
}

TransactionalRouteInfo is how a message was routed.

type TransactionalRouteSummary

type TransactionalRouteSummary struct {
	Configured bool              `json:"configured"`
	Primary    *TransactionalRef `json:"primary,omitempty"`
	Fallback   *TransactionalRef `json:"fallback,omitempty"`
	Policy     string            `json:"policy,omitempty" enum:"automatic,pause_and_ask,warm_only,"`
	// Priority: "First in line on shared providers".
	Priority bool `json:"priority"`
	// Conditions counts the route's rules besides the default one.
	Conditions int `json:"conditions"`
	// System is the System route's provider, offered when there is no
	// Transactional route yet ("Use the System route for now").
	System *TransactionalRef `json:"system,omitempty"`
}

TransactionalRouteSummary is the Transactional route at a glance.

type TransactionalSend

type TransactionalSend struct {
	Template  string                 `json:"template" minLength:"1" maxLength:"64" example:"password-reset" doc:"The template's ID"`
	To        TransactionalAddress   `json:"to"`
	Data      map[string]any         `json:"data,omitempty" doc:"The template's variables"`
	Cc        []TransactionalAddress `json:"cc,omitempty" maxItems:"20"`
	Bcc       []TransactionalAddress `json:"bcc,omitempty" maxItems:"20"`
	Subject   string                 `json:"subject,omitempty" maxLength:"998" doc:"Overrides the template's subject (Liquid)"`
	Preheader string                 `json:"preheader,omitempty" maxLength:"500" doc:"Overrides the template's preheader (Liquid)"`
	From      string                 `` /* 148-byte string literal not displayed */
	ReplyTo   string                 `json:"reply_to,omitempty" maxLength:"320"`
	Tags      []string               `json:"tags,omitempty" maxItems:"10" doc:"Returned with every webhook event of the message"`
	// Metadata is key–value pairs returned with every webhook event.
	Metadata    map[string]string              `json:"metadata,omitempty"`
	Attachments []TransactionalAttachmentInput `json:"attachments,omitempty" maxItems:"20"`
	SendAt      *time.Time                     `json:"send_at,omitempty" doc:"Send later, up to 72 hours ahead"`
	// Language picks a language version (es, pt-BR); without it the linked
	// contact's language is used, then the workspace's fallback.
	Language string `` /* 152-byte string literal not displayed */
	// Localize writes values that are sentences, dates or prices in the
	// language of the version the send picks (its content language code,
	// "" without language versions); Data has them in English. Only
	// ReputeCast's own senders set it (Earn's member emails), never the API.
	Localize func(language string) map[string]any `json:"-"`
}

TransactionalSend is one message: a template, a recipient and the template's variables.

type TransactionalSendResult

type TransactionalSendResult struct {
	ID     string     `json:"id" example:"0192f1c4-7b2e-7c51-9d0a-3f5e8b1a2c44"`
	Status string     `` /* 131-byte string literal not displayed */
	SendAt *time.Time `json:"send_at,omitempty"`
	Test   bool       `json:"test,omitempty" doc:"Sent with a test-mode key"`
	Detail string     `json:"detail,omitempty"`
}

TransactionalSendResult answers an accepted message (202).

type TransactionalSenderOption

type TransactionalSenderOption struct {
	ID       string `json:"id"`
	Name     string `json:"name"`
	Email    string `json:"email"`
	ReplyTo  string `json:"replyTo"`
	Domain   string `json:"domain"`
	Verified bool   `json:"verified"`
}

TransactionalSenderOption is a sender the Transactional stream can use: a sender on a domain marked for transactional mail.

type TransactionalSenderRef

type TransactionalSenderRef struct {
	ID    string `json:"id"`
	Name  string `json:"name"`
	Email string `json:"email"`
}

TransactionalSenderRef is a template's From.

type TransactionalSendingKey

type TransactionalSendingKey struct {
	ID            string     `json:"id"`
	Name          string     `json:"name"`
	Masked        string     `json:"masked"`
	Preset        string     `json:"preset" enum:"send_only,smtp,"`
	Mode          string     `json:"mode" enum:"live,test"`
	Templates     []string   `json:"templates"`
	Categories    []string   `json:"categories" doc:"Category names the key is limited to"`
	TestAddresses []string   `json:"testAddresses"`
	RatePerSecond int        `json:"ratePerSecond"`
	CreatedAt     time.Time  `json:"createdAt"`
	CreatedBy     string     `json:"createdBy"`
	ExpiresAt     *time.Time `json:"expiresAt,omitempty"`
	Expired       bool       `json:"expired"`
	LastUsedAt    *time.Time `json:"lastUsedAt,omitempty"`
	LastUsedIP    string     `json:"lastUsedIp,omitempty"`
}

TransactionalSendingKey is a key that can send.

type TransactionalSettings

type TransactionalSettings struct {
	LinkContacts         bool    `json:"linkContacts" doc:"Link recipients who match a contact to that contact (never creates contacts)"`
	ContentRetentionDays int     `json:"contentRetentionDays" minimum:"0" maximum:"90"`
	AlertBounceRate      float64 `json:"alertBounceRate" doc:"Percent of a template's messages in an hour"`
	AlertFailed          int     `json:"alertFailed" doc:"Failed messages in an hour"`
	AlertMedianSeconds   int     `json:"alertMedianSeconds" doc:"Median delivery time over an hour"`
	// Defaults for new templates.
	DefaultSender      *TransactionalSenderRef `json:"defaultSender,omitempty"`
	DefaultReplyTo     string                  `json:"defaultReplyTo"`
	DefaultTrackOpens  bool                    `json:"defaultTrackOpens"`
	DefaultTrackClicks bool                    `json:"defaultTrackClicks"`
	// Senders are the verified Transactional senders to pick from.
	Senders []TransactionalSenderOption `json:"senders"`
	// ProductName is what recipients see ("Notifications from Acme Cloud"):
	// the default sender's name.
	ProductName string     `json:"productName"`
	UpdatedAt   *time.Time `json:"updatedAt,omitempty"`
	UpdatedBy   string     `json:"updatedBy,omitempty"`
	// CanEdit is transactional:publish; Reason says who can help otherwise.
	CanEdit bool   `json:"canEdit"`
	Reason  string `json:"reason,omitempty"`
}

TransactionalSettings is Settings › Transactional (except categories).

type TransactionalSettingsInput

type TransactionalSettingsInput struct {
	LinkContacts         bool    `json:"linkContacts"`
	ContentRetentionDays int     `json:"contentRetentionDays" minimum:"0" maximum:"90"`
	AlertBounceRate      float64 `json:"alertBounceRate" minimum:"0.1" maximum:"100"`
	AlertFailed          int     `json:"alertFailed" minimum:"1" maximum:"100000"`
	AlertMedianSeconds   int     `json:"alertMedianSeconds" minimum:"1" maximum:"3600"`
	DefaultSenderID      string  `json:"defaultSenderId,omitempty" doc:"A Transactional sender, or empty"`
	DefaultReplyTo       string  `json:"defaultReplyTo,omitempty" maxLength:"254"`
	DefaultTrackOpens    bool    `json:"defaultTrackOpens"`
	DefaultTrackClicks   bool    `json:"defaultTrackClicks"`
}

TransactionalSettingsInput saves Settings › Transactional.

type TransactionalSetup

type TransactionalSetup struct {
	// BaseURL is the API's transactional base; OpenAPIURL the instance's
	// OpenAPI document.
	BaseURL    string                    `json:"baseUrl"`
	OpenAPIURL string                    `json:"openapiUrl"`
	Limits     TransactionalLimits       `json:"limits"`
	Errors     []TransactionalErrorCode  `json:"errors"`
	Keys       []TransactionalSendingKey `json:"keys"`
	// Senders are the verified Transactional senders: the API's from and
	// the SMTP relay's allowed From addresses.
	Senders []TransactionalSenderOption `json:"senders"`
	Relay   TransactionalRelay          `json:"relay"`
	// CanManageKeys: creating keys needs apikeys:manage.
	CanManageKeys bool     `json:"canManageKeys"`
	KeyHelpers    []string `json:"keyHelpers"`
	// Headers are the relay's optional headers.
	Headers []string `json:"headers"`
}

TransactionalSetup is the Setup tab.

type TransactionalStarter

type TransactionalStarter struct {
	Key         string                  `json:"key" example:"password-reset"`
	Name        string                  `json:"name" example:"Password reset"`
	Description string                  `json:"description"`
	Kind        string                  `json:"kind" enum:"essential,optional" doc:"The kind of category it belongs in"`
	Attachment  bool                    `json:"attachment" doc:"Usually sent with an attachment (a PDF invoice)"`
	Subject     string                  `json:"subject"`
	Preheader   string                  `json:"preheader"`
	Variables   []TransactionalVariable `json:"variables"`
	TestData    []TransactionalTestData `json:"testData"`
	// contains filtered or unexported fields
}

TransactionalStarter is a ready-made template: password reset, sign-in link, email verification, welcome, receipt or invoice, trial ending, team invitation and usage alert. Each comes with its variables declared and test data.

type TransactionalStarterList

type TransactionalStarterList struct {
	Items []TransactionalStarter `json:"items"`
}

TransactionalStarterList is the starter gallery.

type TransactionalStats

type TransactionalStats struct {
	Sent           int64   `json:"sent"`
	Delivered      int64   `json:"delivered"`
	DeliveryRate   float64 `json:"deliveryRate"`
	Bounced        int64   `json:"bounced"`
	BounceRate     float64 `json:"bounceRate"`
	Complained     int64   `json:"complained"`
	ComplaintRate  float64 `json:"complaintRate"`
	Deferred       int64   `json:"deferred"`
	Rejected       int64   `json:"rejected"`
	Failed         int64   `json:"failed"`
	Opened         int64   `json:"opened"`
	Clicked        int64   `json:"clicked"`
	MedianMs       *int64  `json:"medianMs,omitempty"`
	RejectedReason string  `json:"rejectedReason,omitempty" doc:"10 suppressed · 2 opted out"`
}

TransactionalStats are a template's (or the workspace's) numbers over a period. Rates are percentages of sent; MedianMs is from the call to the delivery event (null when nothing was delivered).

type TransactionalSuppressionInfo

type TransactionalSuppressionInfo struct {
	ID     string    `json:"id,omitempty" doc:"The suppression as it is now; empty once it was removed"`
	Reason string    `json:"reason" example:"hard_bounce"`
	Since  time.Time `json:"since"`
	Code   string    `json:"code,omitempty" example:"550 5.1.1"`
	Detail string    `json:"detail,omitempty"`
	Source string    `json:"source" example:"Postmark"`
	Scope  string    `json:"scope,omitempty" enum:"all,marketing"`
}

TransactionalSuppressionInfo is the suppression that stopped a message.

type TransactionalTemplate

type TransactionalTemplate struct {
	ID          string                    `json:"id"`
	Key         string                    `json:"key" doc:"The ID the API sends, fixed after the first publish"`
	KeyLocked   bool                      `json:"keyLocked"`
	Name        string                    `json:"name"`
	Description string                    `json:"description"`
	Category    *TransactionalCategoryRef `json:"category,omitempty"`
	// Draft content.
	Subject     string                  `json:"subject"`
	Preheader   string                  `json:"preheader"`
	EditorMode  string                  `json:"editorMode" enum:"visual,mjml,html"`
	MJML        string                  `json:"mjml"`
	HTML        string                  `json:"html"`
	PlainText   string                  `json:"plainText"`
	Variables   []TransactionalVariable `json:"variables"`
	TestData    []TransactionalTestData `json:"testData"`
	Sender      *TransactionalSenderRef `json:"sender,omitempty"`
	ReplyTo     string                  `json:"replyTo"`
	TrackOpens  bool                    `json:"trackOpens"`
	TrackClicks bool                    `json:"trackClicks"`
	// DraftRevision is the autosave counter: send it back as baseRevision.
	DraftRevision int       `json:"draftRevision"`
	DraftSavedAt  time.Time `json:"draftSavedAt"`
	DraftSavedBy  string    `json:"draftSavedBy"`
	DraftHash     string    `json:"draftHash"`
	// DraftChanges is true when the draft differs from the live version
	// (always true before the first publish).
	DraftChanges  bool       `json:"draftChanges"`
	LiveVersion   *int       `json:"liveVersion,omitempty"`
	LiveSince     *time.Time `json:"liveSince,omitempty"`
	LiveBy        string     `json:"liveBy,omitempty"`
	VersionsCount int        `json:"versionsCount"`
	Archived      bool       `json:"archived"`
	ArchivedAt    *time.Time `json:"archivedAt,omitempty"`
	// Origin is where an imported template came from ({"source":"postmark"}).
	Origin    map[string]any              `json:"origin"`
	CreatedAt time.Time                   `json:"createdAt"`
	UpdatedAt time.Time                   `json:"updatedAt"`
	Access    TransactionalTemplateAccess `json:"access"`
	// Language is the language of the content returned (?language=) and
	// SourceLanguage the one the template is written in (internal/languages).
	Language       string `json:"language"`
	SourceLanguage string `json:"sourceLanguage"`
}

TransactionalTemplate is a template with its draft, as the editor loads it.

type TransactionalTemplateAccess

type TransactionalTemplateAccess struct {
	CanEdit    bool `json:"canEdit"`
	CanPublish bool `json:"canPublish"`
	// CanSendTestToOthers is transactional:send; without it test emails go
	// to your own address only.
	CanSendTestToOthers bool `json:"canSendTestToOthers"`
	CanViewContent      bool `json:"canViewContent"`
	// EditReason and PublishReason explain a disabled control and name who
	// can help ("Publishing needs transactional:publish. Ask …").
	EditReason     string   `json:"editReason,omitempty"`
	PublishReason  string   `json:"publishReason,omitempty"`
	PublishHelpers []string `json:"publishHelpers"`
}

TransactionalTemplateAccess says what the caller may do with a template.

type TransactionalTemplateCreate

type TransactionalTemplateCreate struct {
	Name        string `json:"name" minLength:"1" maxLength:"120"`
	Key         string `json:"key,omitempty" maxLength:"64" doc:"Defaults to the name in lowercase with hyphens"`
	Description string `json:"description,omitempty" maxLength:"300"`
	CategoryID  string `json:"categoryId,omitempty" doc:"Defaults to the first Essential category"`
	Starter     string `json:"starter,omitempty" maxLength:"40" doc:"A starter's key (password-reset, magic-link…)"`
	// FromTemplate copies another template's draft.
	FromTemplate string `json:"fromTemplate,omitempty" maxLength:"64"`
	// Content of an imported template (the importer fills these).
	Subject    string                  `json:"subject,omitempty" maxLength:"998"`
	Preheader  string                  `json:"preheader,omitempty" maxLength:"500"`
	EditorMode string                  `json:"editorMode,omitempty" enum:"visual,mjml,html"`
	MJML       string                  `json:"mjml,omitempty" maxLength:"2000000"`
	HTML       string                  `json:"html,omitempty" maxLength:"2500000"`
	PlainText  string                  `json:"plainText,omitempty" maxLength:"500000"`
	Variables  []TransactionalVariable `json:"variables,omitempty" maxItems:"200"`
	TestData   []TransactionalTestData `json:"testData,omitempty" maxItems:"50"`
	Origin     map[string]any          `json:"origin,omitempty"`
}

TransactionalTemplateCreate starts a template: blank, from a starter, as a copy of another template, or with content (template import).

type TransactionalTemplateList

type TransactionalTemplateList struct {
	Items  []TransactionalTemplateListItem `json:"items"`
	Period string                          `json:"period" enum:"24h,7d,30d"`
	// CanEdit is transactional:edit (New template, Import templates).
	CanEdit        bool   `json:"canEdit"`
	CanPublish     bool   `json:"canPublish"`
	ReadOnlyReason string `json:"readOnlyReason,omitempty"`
}

TransactionalTemplateList is the Templates tab's table.

type TransactionalTemplateListItem

type TransactionalTemplateListItem struct {
	ID          string                    `json:"id"`
	Key         string                    `json:"key"`
	Name        string                    `json:"name"`
	Description string                    `json:"description"`
	Category    *TransactionalCategoryRef `json:"category,omitempty"`
	LiveVersion *int                      `json:"liveVersion,omitempty"`
	// DraftChanges is true when the draft differs from the live version;
	// DraftVersion is the number it would publish as.
	DraftChanges bool               `json:"draftChanges"`
	DraftVersion int                `json:"draftVersion"`
	Archived     bool               `json:"archived"`
	Attachments  bool               `json:"attachments" doc:"Recent messages carried attachments"`
	Stats        TransactionalStats `json:"stats"`
	// Spark is the sent count per bucket of the period (hours for 24 hours,
	// days otherwise), oldest first.
	Spark      []int64    `json:"spark"`
	LastSentAt *time.Time `json:"lastSentAt,omitempty"`
	UpdatedAt  time.Time  `json:"updatedAt"`
	// UsedByProducts is how many published digital products send the
	// template as their delivery email ("Used by 2 products").
	UsedByProducts int `json:"usedByProducts,omitempty"`
}

TransactionalTemplateListItem is one row of the Templates table.

type TransactionalTemplateUpdate

type TransactionalTemplateUpdate struct {
	Name        *string `json:"name,omitempty" minLength:"1" maxLength:"120"`
	Key         *string `json:"key,omitempty" maxLength:"64"`
	Description *string `json:"description,omitempty" maxLength:"300"`
	CategoryID  *string `json:"categoryId,omitempty"`
}

TransactionalTemplateUpdate changes what isn't versioned: name, ID (before the first publish), description and category.

type TransactionalTestData

type TransactionalTestData struct {
	Name string         `json:"name" minLength:"1" maxLength:"80" example:"New user"`
	Data map[string]any `json:"data"`
}

TransactionalTestData is a named JSON sample of a template's variables, used by the preview, the checks and test sends.

type TransactionalTestRender

type TransactionalTestRender struct {
	Name    string `json:"name"`
	Source  string `json:"source" enum:"test_data,last_call"`
	OK      bool   `json:"ok"`
	Subject string `json:"subject,omitempty"`
	// Missing lists the required variables the set lacks.
	Missing []string `json:"missing"`
	// Defaults lists the optional variables that fell back to their default.
	Defaults []string `json:"defaults"`
	Problem  string   `json:"problem,omitempty"`
	// Recipient and At describe a real call ("ops@contoso.example", 10:39).
	Recipient string `json:"recipient,omitempty"`
	At        string `json:"at,omitempty"`
}

TransactionalTestRender is the result of rendering one test data set (or a recent real call) with the template.

type TransactionalTextChange

type TransactionalTextChange struct {
	Before string `json:"before"`
	After  string `json:"after"`
}

TransactionalTextChange is a before and after.

type TransactionalTimelineEntry

type TransactionalTimelineEntry struct {
	At   time.Time `json:"at"`
	Kind string    `` /* 187-byte string literal not displayed */
	// Provider is who handed, retried, delivered or bounced.
	Provider          string `json:"provider,omitempty"`
	ProviderMessageID string `json:"providerMessageId,omitempty"`
	// Code and Detail are the provider's answer ("250 2.6.0", "Queued mail
	// for delivery"), or the error of an attempt.
	Code   string `json:"code,omitempty"`
	Detail string `json:"detail,omitempty"`
	// Status is the API's answer (accepted: 202; rejected: 422).
	Status int `json:"status,omitempty"`
	// To is the provider a failover went to; Down says the provider was
	// marked down.
	To   string `json:"to,omitempty"`
	Down bool   `json:"down,omitempty"`
	// Event and URL describe a webhook delivery, URL a click too.
	Event string `json:"event,omitempty"`
	URL   string `json:"url,omitempty"`
	State string `json:"state,omitempty"`
	// Machine marks an open by a mail client's image proxy.
	Machine bool `json:"machine,omitempty"`
}

TransactionalTimelineEntry is one step of a message's life.

type TransactionalVariable

type TransactionalVariable struct {
	Name        string `json:"name" minLength:"1" maxLength:"64" pattern:"^[A-Za-z_][A-Za-z0-9_]*$" example:"reset_url"`
	Type        string `json:"type" enum:"text,number,boolean,date,url,list,object"`
	Required    bool   `json:"required"`
	Sample      string `json:"sample,omitempty" maxLength:"4000"`
	Default     string `json:"default,omitempty" maxLength:"4000"`
	Sensitive   bool   `json:"sensitive" doc:"Never stored: logs and stored content show ••••••"`
	Description string `json:"description,omitempty" maxLength:"300"`
}

TransactionalVariable is a variable a template declares. Sample is what the editor and the code samples fill in; Default is printed when an optional variable isn't sent. For list and object variables both are JSON text.

type TransactionalVariableChange

type TransactionalVariableChange struct {
	Name    string                 `json:"name"`
	Change  string                 `json:"change" enum:"added,removed,changed"`
	Before  *TransactionalVariable `json:"before,omitempty"`
	After   *TransactionalVariable `json:"after,omitempty"`
	Summary string                 `json:"summary" example:"date · required"`
}

TransactionalVariableChange is a variable added, removed or changed between the live version and the draft.

type TransactionalVariableReport

type TransactionalVariableReport struct {
	Used       []VariableUse `json:"used"`
	Undeclared []VariableUse `json:"undeclared"`
	Unused     []string      `json:"unused"`
}

TransactionalVariableReport compares what a template declares with what it uses.

type TransactionalVersion

type TransactionalVersion struct {
	Version     int       `json:"version"`
	Live        bool      `json:"live"`
	PublishedAt time.Time `json:"publishedAt"`
	PublishedBy string    `json:"publishedBy"`
	AvatarColor string    `json:"avatarColor"`
	Change      string    `json:"change"`
	Subject     string    `json:"subject"`
	SizeBytes   int       `json:"sizeBytes"`
}

TransactionalVersion is one published version in the history.

type TransactionalVersionDetail

type TransactionalVersionDetail struct {
	TransactionalVersion
	Preheader   string                  `json:"preheader"`
	EditorMode  string                  `json:"editorMode"`
	MJML        string                  `json:"mjml"`
	HTML        string                  `json:"html"`
	PlainText   string                  `json:"plainText"`
	Variables   []TransactionalVariable `json:"variables"`
	TestData    []TransactionalTestData `json:"testData"`
	Sender      *TransactionalSenderRef `json:"sender,omitempty"`
	ReplyTo     string                  `json:"replyTo"`
	TrackOpens  bool                    `json:"trackOpens"`
	TrackClicks bool                    `json:"trackClicks"`
	Note        string                  `json:"note"`
}

TransactionalVersionDetail is a version with its content (compare).

type TransactionalVersionList

type TransactionalVersionList struct {
	Items []TransactionalVersion `json:"items"`
	// CanPublish is transactional:publish ("Publish again").
	CanPublish bool `json:"canPublish"`
}

TransactionalVersionList is the version history, newest first.

type TransactionalWebhookDelivery

type TransactionalWebhookDelivery struct {
	Event      string     `json:"event"`
	State      string     `json:"state"`
	At         time.Time  `json:"at"`
	Delivered  *time.Time `json:"deliveredAt,omitempty"`
	StatusCode *int32     `json:"statusCode,omitempty"`
	URL        string     `json:"url"`
}

TransactionalWebhookDelivery is a message.* event sent to an endpoint.

type TranslationDraft

type TranslationDraft struct {
	Language  string
	Subject   string
	Preheader string
	MJML      string
	HTML      string
	PlainText string
	// Revision is the version's own save counter (the editor's
	// baseRevision when it edits that language).
	Revision int
	SavedAt  time.Time
	SavedBy  string
	Hash     string
}

TranslationDraft is a language version of a template's draft.

type TranslationText

type TranslationText struct {
	Subject   string
	Preheader string
	MJML      string
	HTML      string
	Text      string
}

TranslationText is a published language version's text.

type Translations

type Translations interface {
	// SourceLanguage is the language the template is written in.
	SourceLanguage(ctx context.Context, ws *store.Workspace, templateID uuid.UUID) (string, error)
	// Draft is a language version of the draft (404 when it has none).
	Draft(ctx context.Context, ws *store.Workspace, templateID uuid.UUID, lang string) (TranslationDraft, error)
	// SaveDraft stores a language version of the draft: its subject,
	// preheader and content (variables, test data and settings are the
	// template's).
	SaveDraft(ctx context.Context, ws *store.Workspace, p *authz.Principal, templateID uuid.UUID, lang string, in TransactionalDraftSave) (TransactionalDraftSaved, error)
	// Publishing lists the languages publishing the draft publishes, read
	// with q.
	Publishing(ctx context.Context, q *store.Queries, ws *store.Workspace, templateID uuid.UUID) ([]TransactionalPublishLanguage, error)
	// Publish publishes the draft's language versions with a new version
	// of the template, in the publish transaction.
	Publish(ctx context.Context, q *store.Queries, ws *store.Workspace, templateID uuid.UUID, version int) error
	// Changes lists the language versions the draft adds, changes or
	// removes since a published version, read with q.
	Changes(ctx context.Context, q *store.Queries, ws *store.Workspace, templateID uuid.UUID, version int) ([]TransactionalLanguageChange, error)
	// Choose picks the language version of a published template version a
	// message uses.
	Choose(ctx context.Context, q *store.Queries, ws *store.Workspace, templateID uuid.UUID, version int, requested string, contactID *uuid.UUID) (LanguageChoice, error)
	// Record stores the language a message was sent in, in the send's
	// transaction.
	Record(ctx context.Context, q *store.Queries, messageID uuid.UUID, ch LanguageChoice) error
}

Translations are a template's language versions (internal/languages): the draft endpoints take `language`, publishing publishes every version with the template's, and each send picks the version its recipient gets (the language asked for, else the linked contact's, else the fallback).

type VariableUse

type VariableUse struct {
	Name   string `json:"name"`
	Where  string `json:"where" enum:"subject,preheader,body,text"`
	Line   int    `json:"line"`
	Column int    `json:"column"`
}

VariableUse is a variable a template prints or tests, with the first line it appears on (1-based, in the source it was found in).

Directories

Path Synopsis
Package importer brings transactional templates from other providers into ReputeCast (add-on spec §3.8, §5.9): Postmark (Mustachio), SendGrid dynamic templates and Mailgun (Handlebars), Notifuse (Liquid), and MJML or HTML files.
Package importer brings transactional templates from other providers into ReputeCast (add-on spec §3.8, §5.9): Postmark (Mustachio), SendGrid dynamic templates and Mailgun (Handlebars), Notifuse (Liquid), and MJML or HTML files.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL