---
name: configuration-messaging
description: "Configure email and file messaging providers, SMTP transport, sender/authentication, templates, and registration delivery wiring. Use to distinguish parsed settings from actual delivery behavior."
---

# Configuration Messaging

## Purpose

Use this skill to configure `messaging <kind> provider <name>` blocks. The
parser is `caddyfile_messaging.go`.

Messaging is most often needed by registration flows, password recovery, MFA
OTP, or administrative notifications.

`caddyfile_messaging.go` forwards provider subdirectives directly to
`go-authcrunch/pkg/messaging`. Use the authcrunch instruction names exactly;
for example, file providers use `root_dir`, not `rootdir`.

## Email Provider

```caddyfile
{
	security {
		messaging email provider localhost-smtp-server {
			address 127.0.0.1:1025
			protocol smtp
			credentials smtp_root
			sender root@example.com "Example Auth Portal"
			bcc admin@example.com audit@example.com
			template password_recovery templates/password_recovery.tmpl
			template registration_confirmation templates/registration_confirmation.tmpl
			template registration_ready templates/registration_ready.tmpl
			template registration_verdict templates/registration_verdict.tmpl
			template mfa_otp templates/mfa_otp.tmpl
		}
	}
}
```

Email providers require:

- `address <host:port>`.
- `protocol smtp` or `protocol smtps`.
- Exactly one of `credentials <name>` or `passwordless`.
- `sender <email> [display_name]`.

Use `passwordless` instead of `credentials <name>` when the SMTP server does
not require authentication.

In selected go-authcrunch v1.3.4, `smtp` opens a plaintext SMTP connection;
the sender does not negotiate STARTTLS. `smtps` uses implicit TLS with
certificate verification. A server requiring STARTTLS is not supported by
switching `protocol smtp` to port 587. Use an endpoint that supports the chosen
transport; there is no Caddyfile STARTTLS or custom SMTP CA directive here.

The referenced `credentials <name>` object follows
[configuration-credentials](../configuration-credentials/SKILL.md).

For local registration message checks, use the built-in file provider below
with a disposable `root_dir` under this checkout's `tmp/`; no SMTP tool install
is needed. This verifies rendered content, not SMTP authentication, TLS or
recipient delivery. When the task requires SMTP evidence, use an explicitly
configured loopback test server and synthetic credentials, inspect its envelope
recipients as well as message headers, and stop it after the check. Keep any
added test tooling and its output in the repository and pin its version.

## File Provider

```caddyfile
messaging file provider local_outbox {
	root_dir tmp/registration-messages
	sender root@example.com "Example Auth Portal"
	template registration_confirmation templates/registration_confirmation.tmpl
	template registration_ready templates/registration_ready.tmpl
	template registration_verdict templates/registration_verdict.tmpl
}
```

File providers write `.eml` messages under `root_dir`. Authcrunch requires both
`root_dir <path>` and `sender <email> [display_name]`. File providers do not use
`credentials` or `passwordless`.

In v1.3.4, email providers put `bcc <email>...` into a `Bcc` message header but
do not add those addresses to SMTP `RCPT TO`. Do not rely on it for copy
delivery or recipient privacy: recipients can see that header. This is an
upstream sender limitation, not configurable Caddy behavior. File providers
parse and preserve `bcc`, but the file sender writes only `To`; it also omits
the configured sender from the `.eml` content.

Both email and file providers validate and preserve these template IDs:

- `password_recovery`.
- `registration_confirmation`.
- `registration_ready`.
- `registration_verdict`.
- `mfa_otp`.

## Template Directive

Use `template <id> <path>` to add an entry to the provider's `templates` map.
Authcrunch validates the ID and preserves the path, but the provider parser does
not check that the path exists.

Current registration notification rendering does not load provider `template`
paths. It uses embedded English subject/body templates from the sibling
`go-authcrunch` repository, then sends the rendered message through the
configured provider.

Default messaging template files live under:
`https://github.com/greenpau/go-authcrunch/tree/main/pkg/messaging/email_templates/en`
The embedded asset loader strips `email_templates/` and `.template`, so
`registration_confirmation_subject.template` is looked up as
`en/registration_confirmation_subject`.

Default files by validated template ID:

- `registration_confirmation`: `registration_confirmation_subject.template`
  and `registration_confirmation_body.template`.
- `registration_ready`: `registration_ready_subject.template` and
  `registration_ready_body.template`.
- `registration_verdict`: `registration_verdict_subject.template` and
  `registration_verdict_body.template`.
- `password_recovery`: no default messaging subject/body file in
  `pkg/messaging/email_templates`; password recovery UI lives in the portal
  sandbox template, not in the messaging template library.
- `mfa_otp`: no default messaging subject/body file in
  `pkg/messaging/email_templates`.

## Registration Wiring

Registration flows reference messaging providers by name with the historical
`email provider <name>` directive. The referenced provider may be either kind;
authcrunch resolves whether it is an `email` or `file` messaging provider at
send time.

```caddyfile
user registration signup {
	email provider localhost-smtp-server
	admin email admin@example.com
}
```

The registration block belongs to
[configuration-registrations](../configuration-registrations/SKILL.md).

## Fixtures

Use these examples:

- `caddyfile_messaging_test.go`.
- `testdata/caddyfile_adapt/testcase_authenticate_with_registration.Caddyfile`.

The parser test checks encoded instructions. Adapt/resolution and lifecycle
tests verify configuration and replacement, not message delivery. This checkout
has no complete user-registration SMTP E2E. Acceptance for a sender change
needs a disposable recipient server that observes the negotiated transport,
authentication, envelope recipients and rendered confirmation link; a `Bcc`
header alone is not delivery evidence. File-provider acceptance checks private
`.eml` output and content, and reports SMTP behavior as untested.