SMTP & Email Alerts

Overview

ControlBird's SMTP & Email Alerts feature delivers automated email notifications whenever an entity's value changes. It uses the same controller / endpoint / mapper configuration model as the device-integration protocols: a controller manages the service, an endpoint describes the SMTP server connection, and one or more mappers watch specific entities and send mail when their value changes. Encryption is supported through STARTTLS and implicit TLS, message content is template-driven, and per-mapper cooldowns provide rate limiting to prevent email floods.

Use this feature to alert operators about critical conditions, notify teams about system events, or produce change reports, all without writing any code. An optional OAuth attribution mode can send each message from the email address of the signed-in user who made the change, which is useful for audit trails. SMTP is a write-only protocol: ControlBird only sends mail, it never reads a mailbox.

Key Concepts

• Mapper pattern. When a watched entity's value changes, the watching SmtpMapper triggers the controller to send an email. This is the same controller / endpoint / mapper layering used by the protocol integrations.
• Three entity types. A SmtpClientController runs the service, a SmtpClientEndpoint defines the server connection and sender identity, and each SmtpMapper binds one watched entity to a set of recipients and templates.
• Template variables. Subject and body templates support {{value}} (current entity value), {{entity_name}} (the watched entity's path), and {{timestamp}} (ISO 8601 time).
• Rate limiting. A configurable cooldown sets the minimum time between emails for a single mapper.
• OAuth attribution. With UseWriterEmailIfAvailable enabled, a change made by an OpenID Connect user can be sent from that user's OAuthEmail address instead of the endpoint's default sender.
• Header-injection safety. Subject lines are sanitized so template content can never inject extra mail headers.

Architecture

An email-alert integration is assembled from three layers of entities. The controller manages the service lifecycle, the endpoint carries the SMTP server connection and sender identity, and each mapper binds a watched entity to its recipients and message templates.

Entity Reference

SmtpClientController

Manages the overall SMTP email notification service, following the same controller layer used by the device-integration protocols.

SmtpClientEndpoint

Defines the SMTP server connection details, credentials, and sender identity.

SmtpMapper

Watches an entity's value for changes and triggers SMTP notifications with customizable templates and recipients. The last three fields are runtime statistics updated after every send attempt and are read-only.

Template Variables

Subject and body templates accept the following placeholders, expanded at send time:

SMTP Server Configuration

Set the endpoint Host, Port, and Security to match your mail provider. The three security modes are None (plaintext), StartTls (upgrade the connection after connecting), and ImplicitTls (TLS from the first byte).

# Gmail
Host     = smtp.gmail.com
Port     = 587
Security = StartTls
Username = [email protected]
Password = your-app-password
FromAddress = [email protected]

# Microsoft 365
Host     = smtp.office365.com
Port     = 587
Security = StartTls

# Amazon SES
Host     = email-smtp.us-east-1.amazonaws.com
Port     = 465
Security = ImplicitTls

Message Templates

Mapper templates support plain text or HTML. The examples below use the template variables to embed the live value, the entity identifier, and the time of the change.

# Simple plain-text alert
Subject = Alert: {{entity_name}} changed
Body    = Value changed to {{value}} at {{timestamp}}

# HTML report (ContentFormat = Html)
Subject = ControlBird: {{entity_name}} Update
Body    =
  <h2>Value Update</h2>
  <p>Entity: <strong>{{entity_name}}</strong></p>
  <p>New Value: <code>{{value}}</code></p>
  <p><small>{{timestamp}}</small></p>

Recipients

Recipients and CcRecipients are comma-separated lists; surrounding whitespace is trimmed. At least one valid recipient is required for the mapper to send.

Recipients = [email protected], [email protected]

Rate Limiting

Set CooldownMs to throttle a noisy mapper. Any email that would fall inside the cooldown window since the last send is skipped.

# Send at most one email per minute from this mapper
CooldownMs = 60000   # any change within 60s of the last send is skipped

OAuth Email Attribution

When UseWriterEmailIfAvailable is enabled on the endpoint, an email triggered by a user action can be sent from that user's address, which is useful for audit trails. All three of the following conditions must hold:

• UseWriterEmailIfAvailable = true on the endpoint.
• The writer's AuthMethod is OpenID Connect.
• The writer has a non-empty OAuthEmail field.

Common Patterns

• Critical alerts. Watch an alarm or status entity with TriggerMode = OnChange and a short plain-text template so operators get immediate, low-noise notifications.
• HTML status reports. Use ContentFormat = Html with a richly formatted body; the automatic plain-text alternative covers clients that cannot render HTML.
• Throttled high-frequency signals. Pair a frequently changing source with CooldownMs to cap the email rate while still surfacing the latest value.
• Audited operator actions. Enable UseWriterEmailIfAvailable so change notifications carry the originating OpenID Connect user's address.
• Monitoring the service. Watch EmailsSent, LastSentAt, and LastError on each mapper to confirm delivery and catch failures.

Troubleshooting & Limitations

• Gmail authentication errors. Use an App Password when 2-factor authentication is enabled; a normal password will be rejected.
• Controller will not initialize. FromAddress must be a valid email format; an invalid value prevents controller initialization.
• Mapper never sends. The Recipients field cannot be empty: at least one comma-separated address is mandatory. Malformed addresses cause the entire send to fail.
• OAuth From not applied. OAuth email only works for OpenID Connect users; Native and LDAP users cannot use it. If the conditions are not met the default FromAddress is used silently.
• Header injection. Newlines in subject templates would allow header injection, so the service strips them from subjects automatically.
• No retries. The service does not retry failed sends. A failure is recorded in LastError and the send is abandoned.
• Write-only protocol. SMTP only sends mail. There is no inbound or receive path by design.
• Inspecting traffic. The service logs SMTP traffic (MAIL FROM, TO, SUBJECT, and error responses) for diagnosis.