Mursil

Run locally

Mon, 01 Jan 0001 00:00:00 +0000

Use this page when you are changing Mursil. Operators who only need a running stack can follow Setup.

Prerequisites

.NET 10 SDK
Docker, for PostgreSQL, Redis, and Mailpit
The CleanArch Pro packages named in nuget.config

The solution file is Mursil.slnx. Restore with dotnet restore Mursil.slnx.

CleanArch Pro is a NuGet dependency. Do not clone it into this repository and do not add a ProjectReference to its source.

AppHost

The Aspire orchestrator is the day-to-day contributor path:

Run locally

Mon, 01 Jan 0001 00:00:00 +0000

Use this page when you are changing Mursil. Operators who only need a running stack can follow Setup.

Prerequisites

.NET 10 SDK
Docker, for PostgreSQL, Redis, and Mailpit
The CleanArch Pro packages named in nuget.config

The solution file is Mursil.slnx. Restore with dotnet restore Mursil.slnx.

CleanArch Pro is a NuGet dependency. Do not clone it into this repository and do not add a ProjectReference to its source.

AppHost

The Aspire orchestrator is the day-to-day contributor path:

Setup

Mon, 01 Jan 0001 00:00:00 +0000

A Mursil deployment is three processes plus PostgreSQL and Redis: the migrator, Mursil.Server, and Mursil.Admin. The migrator applies schema and the first-party seed, then exits. The server accepts the HTTP API. The admin portal is the operator UI.

What you set

Configuration uses the standard .NET shape. Nested keys use a colon in JSON and a double underscore in environment variables.

Setting	Environment variable	What it does
`Mursil:MultiTenancy`	`Mursil__MultiTenancy`	Deployment tenancy switch. Default `false`.
`Identity:Authority`	`Identity__Authority`	OIDC issuer. Required for a published deployment.
`Identity:Audience`	`Identity__Audience`	Expected API audience. The local default is `mursil-api`.
`Identity:ClientId`	`Identity__ClientId`	Admin portal client id. The local default is `mursil-admin-panel`.
`Identity:ClientSecret`	`Identity__ClientSecret`	Admin portal client secret. Set it from your secret store.
`Email:Smtp:Host`	`Email__Smtp__Host`	SMTP host. Local compose points this at Mailpit.
`Email:Smtp:Port`	`Email__Smtp__Port`	SMTP port.
`Email:Smtp:EnableSsl`	`Email__Smtp__EnableSsl`	Whether the SMTP connection uses TLS.

Copy docker/.env.example to docker/.env for the local image and replace the placeholder values there. Do not commit that file, and do not reuse local placeholders in a shared or published deployment.

Setup

Mon, 01 Jan 0001 00:00:00 +0000

What you set

Configuration uses the standard .NET shape. Nested keys use a colon in JSON and a double underscore in environment variables.

Setting	Environment variable	What it does
`Mursil:MultiTenancy`	`Mursil__MultiTenancy`	Deployment tenancy switch. Default `false`.
`Identity:Authority`	`Identity__Authority`	OIDC issuer. Required for a published deployment.
`Identity:Audience`	`Identity__Audience`	Expected API audience. The local default is `mursil-api`.
`Identity:ClientId`	`Identity__ClientId`	Admin portal client id. The local default is `mursil-admin-panel`.
`Identity:ClientSecret`	`Identity__ClientSecret`	Admin portal client secret. Set it from your secret store.
`Email:Smtp:Host`	`Email__Smtp__Host`	SMTP host. Local compose points this at Mailpit.
`Email:Smtp:Port`	`Email__Smtp__Port`	SMTP port.
`Email:Smtp:EnableSsl`	`Email__Smtp__EnableSsl`	Whether the SMTP connection uses TLS.

First send

Mon, 01 Jan 0001 00:00:00 +0000

A send does not embed HTML from the caller. The caller names a published template, a recipient, and a model. Mursil accepts the work and dispatches it after the HTTP call returns.

Before you send

The template key exists and has a published version for the locale you send.
The model matches that version’s schema.
The application has a provider connection. On a local compose stack the default is Local SMTP, which delivers to Mailpit.
You have an access token for the API audience mursil-api.

With Mursil:MultiTenancy left at false, do not send a tenant id.

First send

Mon, 01 Jan 0001 00:00:00 +0000

A send does not embed HTML from the caller. The caller names a published template, a recipient, and a model. Mursil accepts the work and dispatches it after the HTTP call returns.

Before you send

The template key exists and has a published version for the locale you send.
The model matches that version’s schema.
The application has a provider connection. On a local compose stack the default is Local SMTP, which delivers to Mailpit.
You have an access token for the API audience mursil-api.

With Mursil:MultiTenancy left at false, do not send a tenant id.

Product

Mon, 01 Jan 0001 00:00:00 +0000

Mursil is a fully open-source, standalone product for managing application email. There is no paid edition in this repository. It is a product layer above the CleanArch Pro Communication module. The framework module remains the low-level encrypted queue and delivery foundation. Mursil owns the product surface around that foundation.

A secure, template-first communication control plane for SaaS and enterprise applications.

The job

Product teams stop hard-coding email. They manage communication as a governed surface:

Project layout

Mon, 01 Jan 0001 00:00:00 +0000

Dependencies point inward. Presentation calls application code. Application coordinates the domain. Infrastructure implements what application code defines. The domain project references nothing in the outer layers.

 src/
├── Host/
│ ├── AppHost/ Aspire orchestration and shared config
│ ├── ServiceDefaults/ Health checks, telemetry, service defaults
│ └── Mursil.DevIssuer/ Local OpenID Connect stand-in
├── Mursil/
│ ├── Contracts/ DTOs and the tenancy switch
│ ├── Domain/ Aggregates, ids, smart enums
│ ├── Application/ Handlers, validators, delivery ports
│ ├── Client/ Transactional send client
│ ├── Integration/ Host package: send, template push, status
│ ├── Infrastructure/ EF Core, dispatch, SMTP transport
│ ├── Modules/
│ │ ├── Templates/ Template handlers and HTTP endpoints
│ │ └── Providers/ Provider and sender-domain handlers and endpoints
│ └── Presentation/
│ ├── Mursil.AspNetCore/ Request context and shared policies
│ ├── Mursil.Server/ Minimal API host
│ ├── Mursil.Admin/ Blazor admin portal
│ └── Mursil.Migrator/ Migrations and first-party seed
└── Tests/Mursil/ Domain, application, and integration tests

Packaged projects

These projects set IsPackable and publish a package id:

Project layout

Mon, 01 Jan 0001 00:00:00 +0000

 src/
├── Host/
│ ├── AppHost/ Aspire orchestration and shared config
│ ├── ServiceDefaults/ Health checks, telemetry, service defaults
│ └── Mursil.DevIssuer/ Local OpenID Connect stand-in
├── Mursil/
│ ├── Contracts/ DTOs and the tenancy switch
│ ├── Domain/ Aggregates, ids, smart enums
│ ├── Application/ Handlers, validators, delivery ports
│ ├── Client/ Transactional send client
│ ├── Integration/ Host package: send, template push, status
│ ├── Infrastructure/ EF Core, dispatch, SMTP transport
│ ├── Modules/
│ │ ├── Templates/ Template handlers and HTTP endpoints
│ │ └── Providers/ Provider and sender-domain handlers and endpoints
│ └── Presentation/
│ ├── Mursil.AspNetCore/ Request context and shared policies
│ ├── Mursil.Server/ Minimal API host
│ ├── Mursil.Admin/ Blazor admin portal
│ └── Mursil.Migrator/ Migrations and first-party seed
└── Tests/Mursil/ Domain, application, and integration tests

Packaged projects

These projects set IsPackable and publish a package id:

Add a feature

Mon, 01 Jan 0001 00:00:00 +0000

A feature is a folder, not a new layer. Copy the nearest existing slice. Application/Features/Messages/GetMessageStatus/ is a small read. Application/Features/Branding/CreateBrandProfile/ is a small write. Template and provider behavior already live under src/Mursil/Modules/.

Order of work

Decide the rule. If the rule is an invariant (a version cannot publish twice, a domain name is required), put it on the domain type. If it is coordination (load, validate, save), put it in the handler.
Add the contract in Mursil.Contracts when the HTTP body or response gains a field. Keep the DTO free of behavior.
Add the handler as a MediatR IRequestHandler. Place a FluentValidation validator beside it when the command has input rules. Return a Result. Do not throw for a validation failure the caller can correct.
Persist through a repository or specification. Do not put an EF Core query in the handler.
Translate HTTP in the endpoint. The endpoint reads headers through MursilRequestContextResolver, sends the command, and maps Result to a status code. It does not decide business outcomes.
Add an admin page only when an operator must see the feature. Pages live in Mursil.Admin and call IMursilOperationsClient. Authorize the page with an existing policy (Viewer, TemplateEditor, Operators, TenantOwner).
Test the behavior. Domain rules belong in src/Tests/Mursil/Core/Mursil.Domain.UnitTests. Handler behavior belongs in src/Tests/Mursil/Application/Mursil.Application.UnitTests. Run those projects with dotnet run --project.

Endpoint shape

Mursil.Server groups every product route under /api/v1/mursil:

Add a feature

Mon, 01 Jan 0001 00:00:00 +0000

Order of work

Decide the rule. If the rule is an invariant (a version cannot publish twice, a domain name is required), put it on the domain type. If it is coordination (load, validate, save), put it in the handler.
Add the contract in Mursil.Contracts when the HTTP body or response gains a field. Keep the DTO free of behavior.
Add the handler as a MediatR IRequestHandler. Place a FluentValidation validator beside it when the command has input rules. Return a Result. Do not throw for a validation failure the caller can correct.
Persist through a repository or specification. Do not put an EF Core query in the handler.
Translate HTTP in the endpoint. The endpoint reads headers through MursilRequestContextResolver, sends the command, and maps Result to a status code. It does not decide business outcomes.
Add an admin page only when an operator must see the feature. Pages live in Mursil.Admin and call IMursilOperationsClient. Authorize the page with an existing policy (Viewer, TemplateEditor, Operators, TenantOwner).
Test the behavior. Domain rules belong in src/Tests/Mursil/Core/Mursil.Domain.UnitTests. Handler behavior belongs in src/Tests/Mursil/Application/Mursil.Application.UnitTests. Run those projects with dotnet run --project.

Endpoint shape

Mursil.Server groups every product route under /api/v1/mursil:

Architecture

Mon, 01 Jan 0001 00:00:00 +0000

Mursil follows Vertical Slice Architecture inside Clean Architecture. Dependencies point inward. Presentation calls Application. Application coordinates Domain. Infrastructure implements what Application defines. Domain references nothing in the outer layers.

Use cases go through MediatR. HTTP endpoints do not contain business rules. Persistence goes through repositories and specifications. Expected business failures use the Result pattern rather than exceptions thrown for validation.

Source layout

src/
├── Host/
│ ├── AppHost/ .NET Aspire: PostgreSQL, Redis, Mailpit, Migrator, Server, Admin
│ └── ServiceDefaults/ health, OpenTelemetry, shared service defaults
└── Mursil/
 ├── Domain/ aggregates, strongly typed ids, smart enums
 ├── Application/ handlers, commands, validators
 ├── Contracts/ DTOs and request types
 ├── Client/ transactional email client seed
 ├── Integration/ host package: send, draft template push, redacted status
 ├── Infrastructure/ EF Core, dispatch, providers
 └── Presentation/
 ├── Mursil.Server/ Minimal API host
 ├── Mursil.Admin/ Blazor admin portal
 └── Mursil.Migrator/ migrations and first-party seeding

Tests live under src/Tests/Mursil/. The solution file is Mursil.slnx.

Templates

Mon, 01 Jan 0001 00:00:00 +0000

A template is a logical definition owned by an application. Callers address it by a template key. Display names can change. Keys should not, because send requests name the key and not a version.

A template version is the content that can be published. An email version carries a subject, preheader, HTML body, plain-text body, locale, a model-schema snapshot, and a brand binding. Bodies are Fluid templates. A model value is written as {{ orderNumber }}.

Templates

Mon, 01 Jan 0001 00:00:00 +0000

A template is a logical definition owned by an application. Callers address it by a template key. Display names can change. Keys should not, because send requests name the key and not a version.

Branding

Mon, 01 Jan 0001 00:00:00 +0000

Branding is separate from the template body. The template holds the message. A brand profile holds the look and the legal frame: from-name, product name, logo, colors, footer, support link, legal address, and unsubscribe policy.

Open Branding. Name and from-name are required. Theme JSON is a retained bag for social links and accessibility settings. The helper text on the form shows the shape {"social":{},"accessibility":{}}.

Status

A new profile is a draft until you activate it. The list shows each profile’s status. Activate marks that profile as the active one for the scope. Render uses the active profile, together with any brand binding stored on the template version.

Branding

Mon, 01 Jan 0001 00:00:00 +0000

Status

Concepts

Mon, 01 Jan 0001 00:00:00 +0000

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.

HTTP API

Mon, 01 Jan 0001 00:00:00 +0000

Mursil.Server exposes the product API under /api/v1/mursil. In Development it also maps an OpenAPI document and a Scalar reference UI. The .NET client of the send, push, and status subset is Mursil.Integration.

Health for the process is GET /health.

Authentication

Send a bearer token whose audience is mursil-api. Scopes:

Scope	Allows
`mursil.messages.send`	Send, batch send, cancel, status, engagement, and inbound replies.
`mursil.templates.manage`	Template routes, preview, lint, test send, and brand profiles.

A portal role is an alternative to the matching scope. The claim type is role.

HTTP API

Mon, 01 Jan 0001 00:00:00 +0000

Health for the process is GET /health.

Authentication

Send a bearer token whose audience is mursil-api. Scopes:

Scope	Allows
`mursil.messages.send`	Send, batch send, cancel, status, engagement, and inbound replies.
`mursil.templates.manage`	Template routes, preview, lint, test send, and brand profiles.

A portal role is an alternative to the matching scope. The claim type is role.

Extension points

Mon, 01 Jan 0001 00:00:00 +0000

Extend Mursil at the seams below. A new product behavior is still a vertical slice, as Add a feature describes. These interfaces are the places the slice plugs in.

Calling Mursil

Mursil.Integration (AddMursilIntegration) is the supported host package. It registers:

ITransactionalEmailSender, ICommunicationQueue, and IEmailEngine, so a host that already speaks those abstractions can point them at Mursil
IMursilIntegrationClient for draft template push and status lookup
a Refit client for POST /api/v1/mursil/messages/email, POST /api/v1/mursil/templates/push, and GET /api/v1/mursil/messages/status

IMursilIntegrationTenantAccessor supplies a tenant id for one call. The package reads accessors first, then Mursil:Integration:DefaultTenantId. It omits the tenant on the wire when Mursil:MultiTenancy is false.

Extension points

Mon, 01 Jan 0001 00:00:00 +0000

Extend Mursil at the seams below. A new product behavior is still a vertical slice, as Add a feature describes. These interfaces are the places the slice plugs in.

Calling Mursil

Mursil.Integration (AddMursilIntegration) is the supported host package. It registers:

ITransactionalEmailSender, ICommunicationQueue, and IEmailEngine, so a host that already speaks those abstractions can point them at Mursil
IMursilIntegrationClient for draft template push and status lookup
a Refit client for POST /api/v1/mursil/messages/email, POST /api/v1/mursil/templates/push, and GET /api/v1/mursil/messages/status

Identity and tenancy

Mon, 01 Jan 0001 00:00:00 +0000

Mursil does not store users. Kayan, or any OIDC server, authenticates. Mursil authorizes the JWT.

Authority

Identity:Authority is the issuer. Identity:Audience for the API is mursil-api. The admin client id is mursil-admin-panel.

An empty authority does not open the portal and does not fall back to a local issuer. Admin refuses to start until Identity:Authority and Identity:ClientSecret are set. Server validates bearer tokens against the configured authority.

The dev issuer exists only for local click-through. Mursil:DevIssuer defaults to false. AppHost turns it on for local development. Published images do not. See Getting started.

Providers

Mon, 01 Jan 0001 00:00:00 +0000

A provider connection is how Mursil reaches a mail transport. The portal stores a name, a kind, and a settings secret reference. It does not store the secret itself.

What a local stack uses

Local delivery is Mailpit over SMTP. Compose sets Email:Smtp:Host to mailpit and Email:Smtp:Port to 1025. The first-party seed creates a connection named Local SMTP with the reference env:Email:Smtp and makes it the application default.

The seed can also create a Local capture connection of kind TestSink. That kind records the attempt inside Mursil. Mailpit is the place to read a rendered message. Neither one places mail in a recipient inbox.

Providers

Mon, 01 Jan 0001 00:00:00 +0000

A provider connection is how Mursil reaches a mail transport. The portal stores a name, a kind, and a settings secret reference. It does not store the secret itself.

What a local stack uses

Getting started

Mon, 01 Jan 0001 00:00:00 +0000

A contributor can run Mursil and open the admin portal without cloning Kayan. A published deployment still needs a real OIDC authority.

Prerequisites: .NET SDK 10, Docker, and the CleanArch Pro NuGet packages on the feeds in nuget.config. The local feed is cleanarch-pro/.local-packages.

Docker Compose

cp docker/.env.example docker/.env
bash scripts/docker-local.sh

On Windows, ./scripts/docker-local.ps1. Do not commit docker/.env.

The script builds local images and starts Mailpit, the dev issuer, the migrator, Server, and Admin. It does not push an image.

Sender domains

Mon, 01 Jan 0001 00:00:00 +0000

A sender domain is the domain in the From address. Mursil tracks its verification state and the DNS records that support it: SPF, DKIM, and DMARC.

Open Sender domains. The table shows the domain, status, record types, and the time it was verified.

Status

Status	Meaning
`Pending`	Created, not yet verified.
`Verified`	DNS lookup matched the records Mursil expects.
`Failed`	Verification ran and did not match.
`Disabled`	The domain is turned off.

The local seed creates mursil.dev with the from address no-reply@mursil.dev. That domain is a local sender identity. It does not by itself make Mailpit deliver to the public internet.

Sender domains

Mon, 01 Jan 0001 00:00:00 +0000

A sender domain is the domain in the From address. Mursil tracks its verification state and the DNS records that support it: SPF, DKIM, and DMARC.

Open Sender domains. The table shows the domain, status, record types, and the time it was verified.

Status

Status	Meaning
`Pending`	Created, not yet verified.
`Verified`	DNS lookup matched the records Mursil expects.
`Failed`	Verification ran and did not match.
`Disabled`	The domain is turned off.

The local seed creates mursil.dev with the from address no-reply@mursil.dev. That domain is a local sender identity. It does not by itself make Mailpit deliver to the public internet.

Configuration

Mon, 01 Jan 0001 00:00:00 +0000

Some settings are deployment configuration. They are not forms in the admin portal. Set them in the environment, user secrets, or the host configuration before the process starts. Do not commit real secrets.

Identity

Setting	Purpose
`Identity:Authority`	OIDC issuer. Required. Empty does not open the portal.
`Identity:ClientSecret`	Admin client secret. Admin will not start without it.
`Identity:Audience`	`mursil-api`
`Mursil:DevIssuer`	Default false. Local hosts set it true to start the demo issuer.

Docker equivalents are IDENTITY_AUTHORITY, IDENTITY_CLIENT_SECRET, IDENTITY_AUDIENCE, and MURSIL_DEV_ISSUER.

Settings

Mon, 01 Jan 0001 00:00:00 +0000

Settings is the per-application control surface. It is not a billing plan. The card says so on the page.

Application controls

Control	Effect
Sandbox credential	Sends are accepted with state `Sandbox` and are not handed to the provider.
Sends per minute	A limit for the application. Leave the field empty for no limit.
Default provider connection	The connection used when a send does not name `providerConnectionId` and the connection is healthy.

Save writes three API calls: sandbox, rate limit, and default provider. The provider list is the same list as Providers.

Settings

Mon, 01 Jan 0001 00:00:00 +0000

Settings is the per-application control surface. It is not a billing plan. The card says so on the page.

Application controls

Control	Effect
Sandbox credential	Sends are accepted with state `Sandbox` and are not handed to the provider.
Sends per minute	A limit for the application. Leave the field empty for no limit.
Default provider connection	The connection used when a send does not name `providerConnectionId` and the connection is healthy.

Save writes three API calls: sandbox, rate limit, and default provider. The provider list is the same list as Providers.

Operations

Mon, 01 Jan 0001 00:00:00 +0000

After a send is accepted, operators watch delivery on the portal. The figures below are from a local portal: counts will differ, and an empty failure list is a healthy local stack.

Dashboard

Dashboard is the first page after sign-in for a viewer. It summarizes template count, send volume, failure rate, dead-letter backlog, provider health, and suppressions. Delivery lifecycle splits accepted work, deliveries, failures, and suppressions. Recipient domains lists domains that failed, when any have.

Operations

Mon, 01 Jan 0001 00:00:00 +0000

After a send is accepted, operators watch delivery on the portal. The figures below are from a local portal: counts will differ, and an empty failure list is a healthy local stack.

Dashboard

Sending mail

Mon, 01 Jan 0001 00:00:00 +0000

Integration is POST /api/v1/mursil/messages/email and the Mursil.Integration package. Production send uses a published template version. A draft is not live.

Request

POST /api/v1/mursil/messages/email
Authorization: Bearer <access-token>
X-Mursil-ApplicationId: 22222222-2222-4222-8222-222222222222
X-Mursil-ClientId: mursil-platform-service
Content-Type: application/json

{
 "templateKey": "mursil.identity.password-reset",
 "recipient": {
 "email": "user@example.com",
 "displayName": "Ayesha"
 },
 "locale": "en",
 "model": {
 "userName": "Ayesha",
 "resetUrl": "https://identity.example.com/reset?token=example",
 "expiresAt": "2026-05-15T12:00:00Z"
 },
 "idempotencyKey": "password-reset:user-123:2026-05-15T11:45Z",
 "correlationId": "auth-flow-abc123"
}

Field	Required	Meaning
`templateKey`	yes	Published template key.
`recipient.email`	yes	Recipient. Status responses do not echo it.
`recipient.displayName`	no	Display name.
`locale`	no	Requested locale.
`model`	yes	Keys match the published schema.
`idempotencyKey`	yes	One delivery per key.
`correlationId`	no	Caller correlation for status lookup.
`notBefore`	no	UTC time. The message stays accepted until then.
`attachments`	no	File name, content type, and base64 bytes. Oversize or disallowed types are rejected before queueing.
`allowLocaleFallback`	no	Default true. False returns not-found when that locale is unpublished.
`providerConnectionId`	no	Optional provider guid. Empty keeps the router order.

The API accepts the request and returns a message request id. It does not wait for the provider. A successful repeat of the same idempotency key returns the existing request and does not create a second delivery. The same key with a different payload is a conflict.

Delivery and operations

Mon, 01 Jan 0001 00:00:00 +0000

The caller receives an accepted response. Delivery happens after that, on the worker. Operators watch the result. They do not sit on the provider’s HTTP call.

States

The platform state machine is explicit. Handlers do not invent status strings.

Received
Accepted
Rejected
Rendering
RenderFailed
QueuedForDelivery
Delivering
Sent
RetryScheduled
Failed
DeadLettered
Suppressed
Cancelled

Typical path: Accepted, Rendering, QueuedForDelivery, Delivering, Sent. A transient provider failure goes to RetryScheduled and later back to QueuedForDelivery. Exhausted retries become DeadLettered. A suppression match can move an accepted message to Suppressed. A scheduled message can be Cancelled before it sends.

FAQ

Mon, 01 Jan 0001 00:00:00 +0000

Do I pick a tenant in the portal?

No. There is no tenant picker. Set Mursil:MultiTenancy (environment Mursil__MultiTenancy, or MURSIL_MULTI_TENANCY in Docker Compose). The default is false. While it is false, callers omit the tenant id and the deployment keeps a single internal tenant. Set it to true only when one deployment serves many customer organizations. The header chip labeled Tenant scope is a status label.

The admin portal will not start.

Identity:Authority and Identity:ClientSecret must be set. An empty authority does not open the portal. On a local run with MURSIL_DEV_ISSUER=true, compose points both Server and Admin at https://dev-issuer:8443. The browser needs 127.0.0.1 dev-issuer in the hosts file. A published deployment sets MURSIL_DEV_ISSUER=false and Identity:Authority to your own OpenID Connect issuer.

FAQ

Mon, 01 Jan 0001 00:00:00 +0000

Do I pick a tenant in the portal?

The admin portal will not start.

Admin portal

Mon, 01 Jan 0001 00:00:00 +0000

The portal is the operator surface. External products link privileged users here. They do not rebuild these screens.

The captures below were taken on 26 October 2026, between 1:28 and 1:29 AM PKT, at 1860×1080, against a local Aspire admin on https://localhost:7006. The address bar shows the local development certificate. Docker Compose serves the same portal at https://localhost:8089/. The signed-in user chip is MD, role SystemAdmin, with tenant scope, Email v1, and Operational in the header.

Security

Mon, 01 Jan 0001 00:00:00 +0000

Mursil carries identity mail, invitations, payment notices, and other messages that affect account access. Treat that as an account-security surface, not as a marketing tool that happens to send HTML.

Controls that are in the product

Portal authentication is OIDC. There is no local user database to dump.
Roles are least privilege. Viewer can read health. Template editing, provider changes, and delivery actions are separate policies.
Tenant and application scope are part of authorization and of queries. A new endpoint has to opt in.
Provider credentials are references (env: or secret:). Raw secrets do not belong in portal fields, logs, or suppression import.
Status and integration events redact the recipient. Attachment bytes stay in the database. Accepted events do not carry the file.
Idempotency stops a retry storm from sending a second security mail.
Provider callbacks are signed (X-Mursil-Provider-Signature, X-Mursil-Provider-Timestamp).
Preference and tracking links are HMAC-signed. Security mail is excluded from the public preference center.
High-risk template keys go through review before publish. Published versions are immutable, so a sent message can be explained later.
Operator actions are audited.
Integration events use a transactional outbox. Mursil does not hand the payload to an outside broker inside the request.

Mursil:Edition can cap applications, failover, and extra providers. Unset means those gates are open. There is no usage billing in this repository.

Reference

Mon, 01 Jan 0001 00:00:00 +0000

Routes below are on Mursil.Server. The versioned group is /api/v1/mursil. Preference and tracking routes are on the site root.

Roles and scopes

Claim `role`	Notes
SystemAdmin	Platform owner. SuperAdmin is an alias.
TenantOwner	Can create providers and applications.
TenantAdmin	Tenant administration. Included in transactional send.
TemplateEditor	Template catalog and versions.
Operator	Delivery actions, audit, provider pause.
Viewer	Dashboards.

Scopes: mursil.messages.send, mursil.templates.manage. Audience: mursil-api.

Recipient routes

Method and path	Auth
`GET /p/{token}`	Anonymous. Signed preference center.
`POST /p/{token}`	Anonymous. Signed preference update.
`GET /t/o/{token}`	Anonymous. Open pixel.
`GET /t/c/{token}`	Anonymous. Signed click redirect.
`POST /api/v1/mursil/preferences/one-click`	Anonymous.

Send and delivery

Method and path	Purpose
`POST /messages/email`	Template send.
`POST /messages/email/batch`	Batch send.
`POST /messages/email/test`	Test-send.
`GET /messages/status`	Redacted status.
`POST /messages/{messageRequestId}/cancel`	Cancel scheduled.
`POST /messages/{messageRequestId}/engagement`	Record engagement.
`POST /messages/replies`	Inbound reply. No mailbox.
`GET /messages/deliveries/triage`	Failure list.
`GET /messages/deliveries/{deliveryId}`	One delivery.
`POST /messages/deliveries/{deliveryId}/retry`	Retry.
`POST /messages/deliveries/{deliveryId}/suppress`	Suppress.
`POST /messages/deliveries/{deliveryId}/resolve`	Resolve.

Prefix every row in this table and the tables below with /api/v1/mursil unless the path already starts with /p/ or /t/.

Mursil

Run locally

Prerequisites link

AppHost link

Run locally

Prerequisites link

AppHost link

Setup

What you set link

Setup

What you set link

First send

Before you send link

First send

Before you send link

Product

The job

Project layout

Packaged projects link

Project layout

Packaged projects link

Add a feature

Order of work link

Endpoint shape link

Add a feature

Order of work link

Endpoint shape link

Architecture

Source layout

Templates

Templates

Branding

Status link

Branding

Status link

Concepts

Template

HTTP API

Authentication link

HTTP API

Authentication link

Extension points

Calling Mursil link

Extension points

Calling Mursil link

Identity and tenancy

Authority

Providers

What a local stack uses link

Providers

What a local stack uses link

Getting started

Docker Compose

Sender domains

Status link

Sender domains

Status link

Configuration

Identity

Settings

Application controls link

Settings

Application controls link

Operations

Dashboard link

Operations

Dashboard link

Sending mail

Request

Delivery and operations

States

FAQ

Do I pick a tenant in the portal? link

The admin portal will not start. link

FAQ

Do I pick a tenant in the portal? link

The admin portal will not start. link

Admin portal

Security

Controls that are in the product

Prerequisites

AppHost

Prerequisites

AppHost

What you set

What you set

Before you send

Before you send

Packaged projects

Packaged projects

Order of work

Endpoint shape

Order of work

Endpoint shape

Status

Status

Authentication

Authentication

Calling Mursil

Calling Mursil

What a local stack uses

What a local stack uses

Status

Status

Application controls

Application controls

Dashboard

Dashboard

Do I pick a tenant in the portal?

The admin portal will not start.

Do I pick a tenant in the portal?

The admin portal will not start.