configuration-messaging

Configuration Messaging

Purpose

Use this skill to configure messaging <kind> provider <name> blocks. The built-in parser is caddyfile_messaging.go; companion modules use caddyfile_messaging_backend.go. The app owns runtime bindings and delivery.

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 [email protected] "Example Auth Portal"
			bcc [email protected] [email protected]
			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.

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.

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.