Notification Channels

Notification channels are the destinations Mantis delivers event notifications to (deployment results, target offline, certificate expiry, and so on). Create and manage them in Lens under Notifications → Channels, or via the /api/v1/notifications/channels API. Managing channels requires the notifications:create, notifications:update, and notifications:delete permissions for creating, editing, and deleting channels respectively.

Supported channel types:

Type	Destination
Email	An SMTP server (see below)
Webhook	An HTTPS endpoint (Standard Webhooks, always HMAC-signed)

Email (SMTP) channels

An email channel delivers notifications through an SMTP server. Configure these fields when creating or editing an email channel:

Field	Required	Description
`smtp_host`	Yes*	SMTP server hostname
`smtp_port`	Yes*	SMTP server port (see TLS modes below)
`smtp_from_address`	Yes*	Envelope sender address (`MAIL FROM`)

* Functionally required but not validated at create/update. These three fields are optional in the API and carry no server-side validation, so a request that omits them succeeds and stores a channel with no SMTP configuration. The failure is deferred and silent until the first delivery, which fails with Email channel is missing smtp_host. Always set all three. | smtp_from_name | No | Display name for the sender | | smtp_username | No | SMTP AUTH username (omit for an unauthenticated relay) | | smtp_password | No | SMTP AUTH password — encrypted at rest and never returned | | smtp_use_tls | No | Whether to use TLS (default: true) |

The password is encrypted with AES-256-GCM, bound to the channel (so a stored secret cannot be reused on another channel), and is never logged or returned by the API.

TLS modes

The transport security mode is derived from smtp_use_tls and the port:

`smtp_use_tls`	Port	Mode
`true`	`465`	Implicit TLS (SMTPS — TLS from the first byte)
`true`	any other (e.g. `587`)	STARTTLS (opportunistic upgrade)
`false`	any	Plaintext (no transport security)

TLS uses the same rustls + aws-lc-rs stack as the rest of Mantis. Leave smtp_use_tls at its true default unless you are sending to a trusted local relay; with plaintext, credentials travel in the clear.

Testing a channel

Use the Test action in Lens (or POST /api/v1/notifications/channels/{id}/test) to send a test message. For an email channel this performs a self-send to smtp_from_address, exercising the full path — DNS/connection, TLS negotiation, AUTH, and message construction — and reports success or the specific failure.

Certificate expiry events

Mandible checks enrolled agent certificates once every 24 hours and raises one of three events per registration:

Event	Raised when the certificate expires	Severity
`certificate_expiring_soon`	within 30 days	Warning
`certificate_expiring_now`	within 7 days	Warning
`certificate_expired`	on or after the expiry date	Error

Revoked registrations are skipped. Each registration/threshold pair notifies at most once per week, so a certificate that stays inside a window does not re-notify daily. Events for a tenant-scoped agent carry that tenant; agents with no tenant are platform-wide.

The same set is reported by GET /api/v1/certificates/expiring, which takes a days threshold.

Delivery and retries

Deliveries are processed by Mandible’s notification worker. A transient failure (connection error, timeout, SMTP 4xx, or a temporary DNS failure) is retried with exponential backoff. A permanent failure (SMTP 5xx reject, an unparseable sender/recipient address, or a missing/undecryptable SMTP configuration) is dead-lettered immediately rather than retried, since a retry cannot succeed. A per-channel circuit breaker pauses delivery to a channel that is failing repeatedly.