SMTP (Simple Mail Transfer Protocol) is a standard protocol used for sending email messages over the internet. The Weble universal gateway SMTP driver acts as an email client that connects to an SMTP server to send emails triggered by the gateway — typically for alerts, notifications, and automated reports.
The driver uses Nodemailer under the hood and supports:
- TLS/SSL encrypted connections (port 465) and STARTTLS (port 587).
- Multiple recipients per address (comma-separated).
- Custom sender and subject per address or as gateway defaults.
- File attachments via the streaming API (e.g. sending a CSV export as email attachment).
- Automatic retry on transient failures (up to 5 retries).
A common use case is to send alarm emails when sensor values exceed thresholds. For example, a route can monitor a temperature sensor (via Modbus, BACnet, or Zigbee) and write to an SMTP address whenever the temperature goes above a critical value — the gateway then sends the alert email automatically.
¶ 1. Getting started
¶ 1.1 Gateway configuration
Create a new gateway and select the SMTP client driver. Configure the SMTP server connection:
- Host: the SMTP server address (e.g.
smtp.gmail.com,smtp.office365.com). - Port:
465for SSL/TLS (recommended) or587for STARTTLS. - Secure: automatically set to
truewhen port is465,falseotherwise. - Username / Password: SMTP authentication credentials.
Optionally configure:
- DefaultFrom: the default sender email address. If left empty, the SMTP username is used.
- DefaultSubject: a default email subject used when no subject is specified in the address.
¶ 1.2 Sending your first email
Once the gateway is started, it verifies the connection to the SMTP server. To send an email, simply insert an address with the recipient's email address as the name:
- Insert a new address with the name
recipient@example.com. - Write a value to this address — the value becomes the email body.
The email is sent immediately with the default sender and default subject.
¶ 1.3 Use with routes
The SMTP driver is typically used as a destination in routes. For example:
- A Modbus temperature sensor is the route source.
- A Blockly function checks if the value exceeds a threshold.
- If the condition is met, the value is written to the SMTP address, which triggers an email.
See the article Email gateway status alerts for a concrete example.
¶ 2. Gateway parameters
| Label | JSON Key | Description |
|---|---|---|
| Name | name | A descriptive name for this SMTP gateway instance. |
| Cluster ID | cluster | Cluster identifier (integer). Use 0 for single-gateway setups. |
| Description | description | Optional description for this gateway. |
| DefaultSubject | defaultSubject | Default email subject used when no subject is specified in the address name. |
| DefaultFrom | defaultFrom | Default sender email address. If left empty, the SMTP authentication username is used as the sender. |
| Froms | froms | Comma-separated list of allowed sender addresses. If set, only these addresses (and the default sender) can be used as the from field. Leave empty to allow only the default sender. |
¶ SMTP connection
| Label | JSON Key | Description |
|---|---|---|
| Host | smtp.host | SMTP server hostname or IP address (e.g. smtp.gmail.com). |
| Port | smtp.port | SMTP server port: 465 (SSL/TLS, recommended) or 587 (STARTTLS). |
| Secure | smtp.secure | Enable SSL/TLS. Automatically set to true when port is 465, false otherwise. |
| Username | smtp.auth.user | SMTP authentication username (usually the email address). |
| Password | smtp.auth.pass | SMTP authentication password. Leave both username and password empty if the server does not require authentication. |
¶ 2.1 Gateway JSON example
{
"smtp": {
"host": "smtp.gmail.com",
"port": 465,
"secure": true,
"auth": {
"user": "alerts@mycompany.com",
"pass": "app-specific-password"
}
},
"defaultSubject": "Gateway Alert",
"defaultFrom": "alerts@mycompany.com",
"froms": ""
}
Multiple allowed senders:
{
"smtp": {
"host": "mail.example.com",
"port": 587,
"secure": false,
"auth": {
"user": "noreply@example.com",
"pass": "password123"
}
},
"defaultSubject": "IoT Notification",
"defaultFrom": "noreply@example.com",
"froms": "alerts@example.com,reports@example.com"
}
¶ 3. Addresses
¶ 3.1 Address format
SMTP addresses encode the recipient, and optionally the sender and subject, in the address name:
[from:]to[:subject]
Where:
- from (optional) — the sender email address. Must be in the
fromslist or be the default sender. - to (required) — one or more recipient email addresses, separated by commas.
- subject (optional) — the email subject for this address. Overrides the gateway's default subject.
¶ Examples
| Address | Sender | Recipient(s) | Subject |
|---|---|---|---|
user@example.com |
default | user@example.com | default |
user@example.com:Alert! |
default | user@example.com | Alert! |
sender@co.com:user@example.com |
sender@co.com | user@example.com | default |
sender@co.com:a@co.com,b@co.com:Wind Alert |
sender@co.com | a@co.com, b@co.com | Wind Alert |
The address form in the UI provides two fields — Email (the recipient) and Subject — to simplify address creation. The addresses are displayed in a tree grouped by recipient and subject.
¶ 3.2 Address parameters
| Label | JSON Key | Description |
|---|---|---|
| Name | name | The email address in the format described above. |
| Description | description | Optional description for this address. |
| Log | log | Logging mode: never, on update, always, or a duration in milliseconds. |
¶ 3.3 Sending emails (writing values)
Writing a value to an SMTP address triggers an email. The value can be:
Simple text — the value is used as the email body:
"The temperature in Room 1 has exceeded 30°C."
JSON object — allows setting additional email options (any Nodemailer message option):
{
"subject": "Custom Subject",
"text": "Plain text body",
"html": "<h1>HTML body</h1><p>With <b>formatting</b></p>"
}
¶ 3.4 Sending attachments
Files from other drivers can be sent as email attachments using the streaming API. When writing a value that contains a name and gateway_id, the SMTP driver interprets it as a file stream reference and attaches the file to the email.
This is typically used in combination with the CSV driver or the FTP driver to send generated files as email attachments.
¶ 3.5 Address auto-creation
If an email is sent to an address that does not yet exist in the gateway, the address is automatically created. This means you can write to any valid email address format without having to manually create it first.
¶ 4. Connection management
The SMTP driver verifies the connection to the SMTP server at startup and periodically (every hour). If the verification fails, the driver restarts to re-establish the connection.
When sending fails, the driver automatically retries up to 5 times with a 500ms delay between attempts before reporting an error.
¶ 5. Developer reference
| Property | Value |
|---|---|
| Address regex | RFC email format: [from:]to[,to2][:subject] |
| Readable | No |
| Writable | Yes (validated against froms whitelist if configured) |
| Auto-creation | Yes — writing to a new email address auto-creates it |
¶ Write value format
String — used as plain text email body:
writeValue('admin@company.com', 'Temperature alert: 35°C')
Object — full Nodemailer mail options:
writeValue('admin@company.com:Alert', {
subject: 'Custom Subject',
text: 'Plain text body',
html: '<h1>HTML body</h1>'
})
File attachment — pass an address reference with name and gateway_id:
writeValue('admin@company.com', {
name: '%ftp/report.csv',
gateway_id: 5,
destinationOptions: { filename: 'report.csv', text: 'See attached report' }
})
¶ Notes
- Port 465 automatically forces
secure: true - Retries up to 5 times on failure (500ms delay)
- Connection verified every hour
- Writes are serialized (one email at a time)