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 endpoint can authenticate with a stored password, or by connecting a Google or Microsoft 365 account instead (see below). An optional OAuth attribution mode can also 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, and that holds for a connected account too: it is authorized to send, not to read the 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.
• Account authentication. Setting an endpoint's AuthType to OAuth2AuthCode connects a Google or Microsoft 365 account and sends through it instead of a stored password. This authenticates the SMTP connection itself, which is a different mechanism from OAuth attribution below: attribution only changes the From address of an outgoing message.
• 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). Authentication is set separately with AuthType: Password for a stored username and password, OAuth2AuthCode to connect a Google or Microsoft 365 account, or None for a relay that needs no authentication.

Connecting a Google or Microsoft 365 account

In the Add Integration wizard, picking Gmail or Microsoft 365 as the provider fills in the server address, port, security mode, and that provider's OAuth endpoints and scope. It cannot fill in an OAuth app of your own, and that step is not optional: Google and Microsoft both require every application to register itself before it can request access to an account, so you register your own app and paste its client ID and secret into the wizard. Expect a real, multi-step setup rather than a single click:

• Gmail: in Google Cloud Console, create a project, enable the Gmail API, configure the OAuth consent screen with the gmail.send scope, and create an OAuth client ID for a web application.
• Microsoft 365: in the Microsoft Entra admin center, register an app, grant it the SMTP.Send and offline_access API permissions, and create a client secret.

<your platform origin>/api/oauth/endpoint/callback

Back in ControlBird, paste the client ID and client secret into the matching provider group, save the endpoint, then use its Connect with OAuth control. A popup carries you through the provider's sign-in and consent screens; when it closes, the endpoint reports itself connected. Tokens refresh automatically before they expire; if a refresh fails, the control changes to Reconnect and the failure is recorded rather than left silent (see OAuthLastError above and LastError on each mapper).

Password authentication and other providers

AuthType = Password still works for any SMTP server that accepts it, including Amazon SES and self-hosted mail relays, and remains the default for new endpoints.

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

# Gmail or Microsoft 365, password authentication (legacy)
Host     = smtp.gmail.com          # or smtp.office365.com
Port     = 587
Security = StartTls
AuthType = Password
Username = [email protected]
Password = your-app-password
FromAddress = [email protected]

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. For an alarm, point TargetEntity at the alarm and set TargetField to CurrentSeverity (written on activation, escalation, and clear alike). The quickest way to set this up is the Add email notification action on any alarm in the Active Alarms app, which creates the wiring for you.
• 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.
• Attribution From not applied. OAuth attribution only works for OpenID Connect users; Native and LDAP users cannot use it. If the conditions are not met the endpoint's FromAddress is used instead, so it must be set, and alarm notifications in particular always fall through to it.
• Account connection fails or stops sending. Check OAuthLastError on the endpoint and LastError on the affected mapper: OAuth failures (a missing token, an expired refresh token, a rejected authentication attempt) are recorded there rather than dropped silently. A stuck connection usually means the account's consent was revoked or the client secret changed; reconnect the endpoint to fix it.
• 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.