Add SMTP send_mail SQL function with configuration and lettre integration

Cargo.toml

@@ -79,6 +79,14 @@ 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 = [
+    "aws-lc-rs",
+    "builder",
+    "rustls-native-certs",
+    "smtp-transport",
+    "tokio1-rustls",
+    "webpki-roots",
+] }
 
 # OpenTelemetry / tracing
 tracing = "0.1"

configuration.md

@@ -41,6 +41,13 @@ 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 host used by the `sqlpage.send_mail` function. Set with `SMTP_HOST` in the environment. |
+| `smtp_port`                                  | 25 (`none`), 465 (`tls`), or 587 (`starttls`)                | SMTP server port. The default depends on `smtp_tls_mode`. Set this explicitly for relays using a nonstandard port. |
+| `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`. `smtp_username` and `smtp_password` must be configured together. |
+| `smtp_from`                                  |                                                              | Default sender address for `sqlpage.send_mail`, optionally including a display name. Individual messages can override it with their `from` property. |
+| `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. |
+| `max_email_attachment_size`                  | 10485760                                                     | Maximum combined decoded size, in bytes, of all attachments in one email. Defaults to 10 MiB. |
 | `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,76 @@
+INSERT INTO sqlpage_functions (
+        "name",
+        "introduced_in_version",
+        "icon",
+        "description_md"
+    )
+VALUES (
+        'send_mail',
+        '0.45.0',
+        'mail',
+        'Sends an email using the SMTP server configured with `SMTP_HOST`.
+
+`SMTP_HOST` contains the relay host name. Set `SMTP_PORT` when the relay does not use the default for the selected encryption mode: 587 for `starttls`, 465 for `tls`, or 25 for `none`.
+
+`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:
+
+- `to`: 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:
+
+- `from`: sender address. It may be omitted when `SMTP_FROM` configures a default sender.
+- `reply_to`: reply-to address.
+
+The function returns `NULL` after the SMTP relay accepts the message and raises an error if the message cannot be sent. The argument is required; passing `NULL` is an error.
+
+### Example
+
+```sql
+set message = json_object(
+    ''to'', ''admin@example.com'',
+    ''from'', ''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(
+    ''to'', ''admin@example.com'',
+    ''reply_to'', $email,
+    ''subject'', ''Website contact form'',
+    ''body'', $message
+);
+select sqlpage.send_mail($mail)
+where $message is not null;
+```
+'
+    );
+
+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 `to`, `subject`, and `body`. Optional properties are `from` (required unless `SMTP_FROM` is configured) and `reply_to`. Unknown properties are rejected to catch misspellings.',
+        'JSON'
+    );

examples/sending emails/README.md

@@ -1,76 +1,31 @@
 # Sending Emails with SQLPage
 
-SQLPage lets you interact with any email service through their API,
-using the [`sqlpage.fetch` function](https://sql-page.com/functions.sql?function=fetch).
+This example sends plain-text email with [`sqlpage.send_mail`](https://sql-page.com/functions.sql?function=send_mail). The included Docker Compose setup uses [Mailpit](https://mailpit.axllent.org/) as a local SMTP server, so no email leaves your computer.
 
-## Why Use an Email Service?
+Run the example:
 
-Sending emails directly from your server can be challenging:
-- Many ISPs block direct email sending to prevent spam
-- Email deliverability requires proper setup of SPF, DKIM, and DMARC records
-- Managing bounce handling and spam complaints is complex
-- Direct sending can impact your server's IP reputation
-
-Email services solve these problems by providing reliable APIs for sending emails while handling deliverability, tracking, and compliance.
+```sh
+docker compose up
+```
 
-## Popular Email Services
+Open http://localhost:8080 to send an email, then inspect it in the Mailpit inbox at http://localhost:8025.
 
-- [Mailgun](https://www.mailgun.com/) - Developer-friendly, great for transactional emails
-- [SendGrid](https://sendgrid.com/) - Powerful features, owned by Twilio
-- [Amazon SES](https://aws.amazon.com/ses/) - Cost-effective for high volume
-- [Postmark](https://postmarkapp.com/) - Focused on transactional email delivery
-- [SMTP2GO](https://www.smtp2go.com/) - Simple SMTP service with API options
+The SMTP server is configured in [`docker-compose.yml`](./docker-compose.yml) with `SMTP_HOST=mailpit`, `SMTP_PORT=1025`, and `SMTP_TLS_MODE=none`. Plaintext mode is intended only for trusted local SMTP servers such as Mailpit.
 
-## Example: Sending Emails with Mailgun
+For a remote SMTP relay, keep the default `SMTP_TLS_MODE=starttls`, or set it to `tls` when the relay requires implicit TLS. Configure `SMTP_USERNAME` and `SMTP_PASSWORD` when authentication is required; SQLPage rejects credentials in plaintext mode.
 
-Here's a complete example using Mailgun's API to send emails through SQLPage:
+The form handler sends the message with a single function call:
 
-### [`email.sql`](./email.sql)
 ```sql
--- Configure the email request
-set email_request = json_object(
-    'url', 'https://api.mailgun.net/v3/' || sqlpage.environment_variable('MAILGUN_DOMAIN') || '/messages',
-    'method', 'POST',
-    'headers', json_object(
-        'Content-Type', 'application/x-www-form-urlencoded',
-        'Authorization', 'Basic ' || encode(('api:' || sqlpage.environment_variable('MAILGUN_API_KEY'))::bytea, 'base64')
-    ),
-    'body', 
-        'from=Your Name <noreply@' || sqlpage.environment_variable('MAILGUN_DOMAIN') || '>'
-        || '&to=' || $to_email
-        || '&subject=' || $subject
-        || '&text=' || $message_text
-        || '&html=' || $message_html
+set message = json_object(
+    'to', :recipient,
+    'from', :sender,
+    'subject', :subject,
+    'body', :body
 );
-
--- Send the email using sqlpage.fetch
-set email_response = sqlpage.fetch($email_request);
-
--- Handle the response
-select 
-    'alert' as component,
-    case 
-        when $email_response->>'id' is not null then 'Email sent successfully'
-        else 'Failed to send email: ' || ($email_response->>'message')
-    end as title;
+set _ = sqlpage.send_mail($message);
 ```
 
-### Setup Instructions
-
-1. Sign up for a [Mailgun account](https://signup.mailgun.com/new/signup)
-2. Verify your domain or use the sandbox domain for testing
-3. Get your API key from the Mailgun dashboard
-4. Set these environment variables in your SQLPage configuration:
-   ```
-   MAILGUN_API_KEY=your-api-key-here
-   MAILGUN_DOMAIN=your-domain.com
-   ```
-
-## Best Practices
+`sqlpage.send_mail` returns `NULL` after the SMTP relay accepts the message. It raises an error when the relay rejects the message or cannot be reached, so statements after the call run only on success.
 
-- If you share your code with others, it should not contain sensitive data like API keys
-  - Instead, use environment variables with [`sqlpage.environment_variable`](https://sql-page.com/functions.sql?function=environment_variable)
-- Implement proper error handling
-- Consider rate limiting for bulk sending
-- Include unsubscribe links when sending marketing emails
-- Follow email regulations (GDPR, CAN-SPAM Act)
+Do not expose an unrestricted form like this publicly. In production, authenticate users, restrict recipients, validate input, and add rate limiting to prevent abuse.

examples/sending emails/docker-compose.yml

@@ -3,5 +3,16 @@ services:
     image: lovasoa/sqlpage:main
     ports:
       - "8080:8080"
+    environment:
+      SMTP_HOST: mailpit
+      SMTP_PORT: 1025
+      SMTP_TLS_MODE: none
     volumes:
       - .:/var/www
+    depends_on:
+      - mailpit
+
+  mailpit:
+    image: axllent/mailpit:v1.30.4
+    ports:
+      - "8025:8025"