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

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.

Coordinate credentials <name> with configuration-credentials.

For local registration or MFA email testing, run a mock SMTP server on the configured address:

go install github.com/emersion/go-smtp/cmd/smtp-debug-server@latest
smtp-debug-server

The common docs examples use 127.0.0.1:1025 with protocol smtp and passwordless. The debug server prints raw SMTP conversations and rendered messages, which helps verify confirmation links, passcodes, BCC recipients, sender identity, and registration metadata. Installing the tool may require network access; use an existing local binary when available.

File Provider

messaging file provider local_outbox {
	root_dir assets/config/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.

Email providers use bcc <email>... when constructing outgoing SMTP messages. File providers parse and preserve bcc, but the current file sender writes only the To recipients into the generated .eml file.

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.

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

Use configuration-registrations for the registration block.

Fixtures

Use these examples:

• caddyfile_messaging_test.go.
• testdata/caddyfile_adapt/testcase_authenticate_with_registration.Caddyfile.