add a demo for sending emails

Author: lovasoa

examples/sending emails/README.md

@@ -0,0 +1,74 @@
+# 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).
+
+## Why Use an Email Service?
+
+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.
+
+## Popular Email Services
+
+- [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
+
+## Example: Sending Emails with Mailgun
+
+Here's a complete example using Mailgun's API to send emails through SQLPage:
+
+```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(
+        'Authorization', 'Basic ' || encode(('api:' || sqlpage.environment_variable('MAILGUN_API_KEY'))::bytea, 'base64')
+    ),
+    'body', 
+        'from=Sender Name <noreply@' || sqlpage.environment_variable('MAILGUN_DOMAIN') || '>'
+        || '&to=' || $to_email
+        || '&subject=' || $subject
+        || '&text=' || $message_text
+        || '&html=' || $message_html
+);
+
+-- 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;
+```
+
+### 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
+
+- 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)

examples/sending emails/email.sql

@@ -0,0 +1,43 @@
+-- Configure the email request
+
+-- Obtain the authorization by encoding "api:YOUR_PERSONAL_API_KEY" in base64
+set authorization = 'YXBpOjI4ODlmODE3Njk5ZjZiNzA4MTdhODliOGUwODYyNmEyLWU2MWFlOGRkLTgzMjRjYWZm';
+
+-- Find the domain in your Mailgun account
+set domain = 'sandbox859545b401674a95b906ab417d48c97c.mailgun.org';
+
+-- Set the recipient email address.
+--In this demo, we accept sending any email to any address.
+-- If you do this in production, spammers WILL use your account to send spam.
+-- Your application should only allow emails to be sent to addresses you have verified.
+set to_email = :to_email;
+
+-- Set the email subject
+set subject = :subject;
+
+-- Set the email message text
+set message_text = :message_text;
+
+set email_request = json_object(
+    'url', 'https://api.mailgun.net/v3/' || $domain || '/messages',
+    'method', 'POST',
+    'headers', json_object(
+        'Content-Type', 'application/x-www-form-urlencoded',
+        'Authorization', 'Basic ' || $authorization
+    ),
+    'body', 
+        'from=Your Name <noreply@' || $domain || '>'
+        || '&to=' || sqlpage.url_encode($to_email)
+        || '&subject=' || sqlpage.url_encode($subject)
+        || '&text=' || sqlpage.url_encode($message_text)
+);
+-- 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;

examples/sending emails/index.sql

@@ -0,0 +1,5 @@
+select 'form' as component, 'Send an email' as title, 'email.sql' as action;
+
+select 'to_email' as name, 'To email' as label, '[email protected]' as value;
+select 'subject' as name, 'Subject' as label, 'Test email' as value;
+select 'textarea' as type, 'message_text' as name, 'Message' as label, 'This is a test email' as value;