Add SMTP send_mail SQL function with configuration and lettre integration

Cargo.toml

@@ -79,6 +79,7 @@ openidconnect = { version = "4.0.0", default-features = false, features = ["acce
 encoding_rs = "0.8.35"
 odbc-sys = { version = "0", optional = true }
 regex = "1"
+lettre = { version = "0.11", default-features = false, features = ["builder", "smtp-transport", "tokio1", "tokio1-native-tls"] }
 
 # OpenTelemetry / tracing
 tracing = "0.1"

configuration.md

@@ -41,6 +41,10 @@ Here are the available configuration options and their default values:
 | `environment`                                 | development                                                 | The environment in which SQLPage is running. Can be either `development` or `production`. In `production` mode, SQLPage will hide error messages and stack traces from the user, and will cache sql files in memory to avoid reloading them from disk. |
 | `cache_stale_duration_ms`                     | 1000 (prod), 0 (dev)                                        | The duration in milliseconds that a file can be cached before its freshness is checked against the filesystem. Defaults to 1000ms (1 second) in production and 0ms in development. |
 | `content_security_policy`                     | `script-src 'self' 'nonce-{NONCE}'`                          | The [Content Security Policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP) to set in the HTTP headers. If you get CSP errors in the browser console, you can set this to the empty string to disable CSP. If you want a custom CSP that contains a nonce, include the `'nonce-{NONCE}'` directive in your configuration string and it will be populated with a random value per request.                                                                                                           |
+| `smtp_host`                                  |                                                              | SMTP server used by the `sqlpage.send_mail` function. Accepts only a host name or `host:port`; if no port is provided, SQLPage uses port 25. Set with `SMTP_HOST` in the environment. |
+| `smtp_username`                              |                                                              | Optional SMTP user name for `sqlpage.send_mail`. When set, SQLPage authenticates to `SMTP_HOST` using this user name and `smtp_password`. Credentials require `smtp_tls_mode` to be `starttls` or `tls`. |
+| `smtp_password`                              |                                                              | Optional SMTP password for `sqlpage.send_mail` when `smtp_username` is set. |
+| `smtp_tls_mode`                              | `starttls`                                                   | Encryption mode for `sqlpage.send_mail`: `starttls` requires a STARTTLS upgrade, `tls` uses TLS from connection start, and `none` permits plaintext only without credentials for trusted local SMTP servers. |
 | `system_root_ca_certificates`                 | false                                                      | Whether to use the system root CA certificates to validate SSL certificates when making http requests with `sqlpage.fetch`. If set to false, SQLPage will use its own set of root CA certificates. If the `SSL_CERT_FILE` or `SSL_CERT_DIR` environment variables are set, they will be used instead of the system root CA certificates. |
 | `max_recursion_depth`                         | 10                                                           | Maximum depth of recursion allowed in the `run_sql` function. Maximum value is 255. |
 | `markdown_allow_dangerous_html`               | false                                                        | Whether to allow raw HTML in markdown content. Only enable this if the markdown content is fully trusted (not user generated). |

examples/official-site/sqlpage/migrations/75_send_mail.sql

@@ -0,0 +1,78 @@
+INSERT INTO sqlpage_functions (
+        "name",
+        "introduced_in_version",
+        "icon",
+        "description_md",
+        "return_type"
+    )
+VALUES (
+        'send_mail',
+        '0.45.0',
+        'mail',
+        'Sends an email using the SMTP server configured with `SMTP_HOST`.
+
+`SMTP_HOST` must contain only a host name or `host:port`; URL schemes and paths are rejected. When no port is specified, SQLPage uses port 25.
+
+`SMTP_TLS_MODE` defaults to `starttls`, which requires a STARTTLS upgrade before sending email or credentials. Set it to `tls` for implicit TLS, commonly used on port 465. Plaintext mode (`none`) is allowed only without credentials and should be used only for trusted local SMTP servers.
+
+If your SMTP server requires authentication, configure `SMTP_USERNAME` and `SMTP_PASSWORD` as well.
+
+The function accepts a single JSON object argument. The required properties are:
+
+- `recipient`: email address to send to, optionally including a display name such as `"Jane Doe <jane@example.com>"`.
+- `subject`: email subject.
+- `body`: plain text email body.
+
+Optional properties:
+
+- `sender`: sender address. Defaults to `SQLPage <sqlpage@localhost>`.
+- `reply_to`: reply-to address.
+
+After the SMTP server accepts the message, the function returns its JSON argument unchanged. It returns `NULL` when passed `NULL`, and raises an error if the message cannot be sent.
+
+### Example
+
+```sql
+set message = json_object(
+    ''recipient'', ''admin@example.com'',
+    ''sender'', ''contact@example.com'',
+    ''subject'', ''New contact form message'',
+    ''body'', ''Hello from SQLPage!''
+);
+select sqlpage.send_mail($message);
+```
+
+### Contact form example
+
+```sql
+select ''form'' as component, ''post'' as method;
+select ''email'' as name, ''email'' as type, true as required;
+select ''message'' as name, ''textarea'' as type, true as required;
+
+set mail = json_object(
+    ''recipient'', ''admin@example.com'',
+    ''reply_to'', $email,
+    ''subject'', ''Website contact form'',
+    ''body'', $message
+);
+select sqlpage.send_mail($mail)
+where $message is not null;
+```
+',
+        'JSON'
+    );
+
+INSERT INTO sqlpage_function_parameters (
+        "function",
+        "index",
+        "name",
+        "description_md",
+        "type"
+    )
+VALUES (
+        'send_mail',
+        1,
+        'message',
+        'A JSON object containing the email to send. Required properties are `recipient`, `subject`, and `body`. Optional properties are `sender` and `reply_to`.',
+        'JSON'
+    );