sqlpage--sqlpage/examples/sending emails/README.md

Sending Emails with SQLPage

SQLPage lets you interact with any email service through their API, using the sqlpage.fetch function.

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 - Developer-friendly, great for transactional emails
• SendGrid - Powerful features, owned by Twilio
• Amazon SES - Cost-effective for high volume
• Postmark - Focused on transactional email delivery
• SMTP2GO - 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:

email.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
);

-- 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
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
• Implement proper error handling
• Consider rate limiting for bulk sending
• Include unsubscribe links when sending marketing emails
• Follow email regulations (GDPR, CAN-SPAM Act)