Step 23: SMTP Email Alerts

3:26

SMTP Protocol Service

ControlBird's SMTP service sends automated email notifications when entity values change. Use it to alert operators about critical conditions, send daily reports, or notify teams about system events.

How It Works

The SMTP service uses the standard mapper pattern: when the watched field on the target entity changes, the mapper triggers the controller to send an email. Which field is watched depends on TargetField, covered below.

Setting Up SMTP

SMTP configuration requires three entities: a SmtpClientController, a SmtpClientEndpoint, and one or more SmtpMapper entities.

1. Create the Controller

The controller manages the overall SMTP service. Create it under your /Root/Controllers folder:

2. Configure the Endpoint

The endpoint defines your SMTP server connection. Add it as a child of the controller:

Connecting Gmail or Microsoft 365

Set AuthType to OAuth2AuthCode, or pick Gmail or Microsoft 365 as the provider in the Add Integration wizard, to send through a connected account instead of a stored password. The connection is authorized to send mail only; it cannot read the mailbox's inbox. Both providers require you to bring your own OAuth app registration (a Google Cloud project or a Microsoft Entra app) with its own client ID and secret; this is a real setup step, not a single click. See the full reference for the exact registration steps.

3. Create Mappers

Each mapper watches a specific entity and sends emails when its value changes:

Template Variables

Use these placeholders in your subject and body templates:

Example Templates

<h2>Value Update</h2>
<p>Entity: <strong>{{entity_name}}</strong></p>
<p>New Value: <code>{{value}}</code></p>
<p><small>{{timestamp}}</small></p>

OAuth Email Integration

When UseWriterEmailIfAvailable is enabled on the endpoint, the SMTP service can send emails from the OAuth user's email address instead of the default FromAddress.

How It Works

Rate Limiting

Use the CooldownMs field to prevent email floods. When set, the mapper will skip sending emails if one was sent within the cooldown period.

Runtime Statistics

Each mapper tracks statistics that you can monitor:

Common SMTP Configurations

Troubleshooting

What's Next?

You've completed the full walkthrough! Here are some advanced topics to explore:

• Faceplate Builder: Create custom device control panels with graphics
• Schematic Builder: Design P&ID diagrams linked to live data
• Certificate Management: Configure TLS for secure device connections
• Config Manager: Version control your entire configuration