Mursil Documentation

Concepts

Mursil separates four ideas that products often collapse into one “email settings” screen.

Template

A template is a logical definition owned by an application. It has a stable template key. Display names can change. Keys should not, because callers send by key.

A template version is the immutable content that can be published. For email, a version carries subject, preheader, HTML body, plain-text body, locale, a model-schema snapshot, and a brand binding mode.

Lifecycle that production send cares about:

  1. Draft. Editable. Not used by production send.
  2. Review and approve, for versions that require it. High-risk keys still need review before publish.
  3. Publish. That version becomes the one send resolves.
  4. Archive. History stays. A rollback publishes a previous version as a new version. Published content is not edited in place.

Rendering uses Fluid. The caller supplies a model. Mursil validates it against the published schema. allowLocaleFallback defaults to true. Set it to false when a missing exact locale must fail instead of falling back.

Branding mode on a version is either a fixed brand profile or a mode that rejects a fixed profile id. FixedProfile requires a profile.

Brand profile

Branding is the tenant’s visual identity, kept off the template so one template can serve many brands. First-class fields are name, from name, product name, logo URL, primary, accent, and background colors, footer text, support link, legal address, unsubscribe policy, and default locale. ThemeJson holds social links and accessibility extras. An empty theme is {"social":{},"accessibility":{}}.

Provider

A provider connection is how a message leaves Mursil: SMTP, SendGrid, TestSink, or a pluggable transport such as Amazon SES, Azure Communication Services, Microsoft Graph, Postmark, or Mailgun. The connection stores a secret reference, env:NAME or secret:path. It does not store a raw password.

Local development already has Mailpit wired as SMTP. Operators do not create a second provider row to “turn on” that local capture.

Routing prefers the application default, then purpose, region, and tenant default or failover. The chosen policy is stored on the delivery.

Sender domain

A sender domain is the From domain, verified with SPF, DKIM, and DMARC. Add one when the deployment has a domain to send from. A local stack may already show a verified row for mursil.dev. That row is seed data, not a prompt to invent another domain.

Application

An application is a product that sends through Mursil. Callers pass its id on X-Mursil-ApplicationId and the OAuth client id on X-Mursil-ClientId. Application controls cover sandbox mode, sends per minute, and the default provider connection.

Message

A message request is one accepted send. It has an idempotency key, an optional correlation id, a recipient, a locale, and a model. Status responses return state and a redacted failure. They do not return the rendered body or the raw recipient address.