Email & SMS Setup Guide

Documentation Index

Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt

Use this file to discover all available pages before exploring further.

​

Table of Contents

1. Overview
2. Email Service (Entra ID & Gmail)
3. SMS Service (Twilio)
4. Template Configuration
5. Rate Limiting & Quotas
6. Cost Optimization
7. Error Handling
8. Testing
9. Troubleshooting

​

Overview

• Email: Microsoft Entra ID (Graph API) or Gmail (Google Workspace) — org-level sending. Configure per organization in HR Settings and Settings → Integrations.
• SMS: Twilio (primary provider)

• send-email-notification - Single notification delivery
• send-pending-notifications - Batch processing
• hr-portal-invite, hr-reference-request, hr-send-communication, hr-test-email - HR recruitment
• automation-executor - Workflow send-email actions
• Signature flows: send-signature-request, send-signature-reminder, auto-signature-reminders use the shared email-provider (Entra/Gmail) per organization.

​

Email Service (Entra ID & Gmail)

​

Microsoft Entra ID (recommended)

1. Configure the Entra ID integration in Settings → Integrations → Microsoft Entra ID (tenant, app registration, admin consent with Mail.Send).
2. Set the sender email in the same page (or in pf_organizations.settings.entra_sender_email).
3. Set ENTRA_CLIENT_SECRET in Supabase secrets (client secret for the app registration).
4. In HR → Settings → Email, select Microsoft Entra ID and optionally set From Email Address / From Name.

​

Gmail (Google Workspace)

1. Google Cloud: Create a project, enable Gmail API, create a service account.
2. Domain-wide delegation: In Google Workspace Admin, grant the service account domain-wide delegation for scope https://www.googleapis.com/auth/gmail.send.
3. Supabase secret: Set the service account JSON as a secret:
   supabase secrets set GMAIL_SERVICE_ACCOUNT_JSON='{"type":"service_account","project_id":"...","private_key_id":"...","private_key":"-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n","client_email":"...@....iam.gserviceaccount.com",...}'
   
4. Per-organization sender: In Settings → Integrations → Google Workspace (Gmail), set Sender email address to the Gmail/Workspace user to impersonate (e.g. recruiting@yourcompany.com). This is stored in pf_organizations.settings.gmail_sender_email.
5. In HR → Settings → Email, select Gmail (Google Workspace) and optionally set From Email Address / From Name.

​

SMS Service (Twilio)

​

1. Create Twilio Account

1. Go to Twilio
2. Sign up for account
3. Verify phone number

​

2. Get Credentials

1. Go to Console → Account → API Keys & Tokens
2. Copy Account SID (starts with AC)

1. Same page as Account SID
2. Click Show next to Auth Token
3. Copy Auth Token

1. Go to Phone Numbers → Manage → Active Numbers
2. Purchase phone number (or use trial number)
3. Copy phone number (format: +1234567890)

​

3. Set Supabase Secrets

# Set Twilio credentials
supabase secrets set TWILIO_ACCOUNT_SID=ACxxxxx
supabase secrets set TWILIO_AUTH_TOKEN=xxxxx
supabase secrets set TWILIO_PHONE_NUMBER=+1234567890

# Verify secrets are set
supabase secrets list

​

4. Configure Edge Function

• TWILIO_ACCOUNT_SID
• TWILIO_AUTH_TOKEN
• TWILIO_PHONE_NUMBER

​

Template Configuration

​

Email Templates

• Use {{variable_name}} syntax
• Variables replaced at send time
• Case-sensitive

Subject: Leave Request {{action}}

Hello {{employee_name}},

Your leave request has been {{action}}.

Details:
- Start Date: {{start_date}}
- End Date: {{end_date}}
- Days: {{days}}

Thank you,
HR Team

await sendEmailNotification({
  recipientEmail: 'user@example.com',
  subject: 'Leave Request {{action}}',
  body: 'Your request has been {{action}}.',
  variables: {
    action: 'approved',
    employee_name: 'John Doe',
    start_date: '2025-01-15',
    end_date: '2025-01-20',
    days: '5'
  }
});

​

SMS Templates

• Single SMS: 160 characters
• Messages > 160 characters are truncated
• Use concise templates

{{action}}: Your leave request for {{start_date}} has been {{status}}. Days: {{days}}

await sendSMSNotification({
  phoneNumber: '+1234567890',
  message: '{{action}}: Your request has been {{status}}.',
  variables: {
    action: 'Leave Request',
    status: 'approved',
    start_date: '2025-01-15',
    days: '5'
  }
});

​

Rate Limiting & Quotas

​

Email (Entra / Gmail) Limits

​

Twilio Limits

• Limited to verified phone numbers
• SMS only to verified numbers

• No daily/monthly limits
• Pay per SMS sent

• No explicit rate limit
• Throttling may occur at very high volumes

​

Platform Limits

• Email: Max 100 emails/hour per organization
• SMS: Max 50 SMS/hour per organization
• Enforced in edge functions

​

Cost Optimization

​

Email Costs (Entra / Gmail)

1. Batch notifications when possible
2. Use send-pending-notifications for batch processing
3. Monitor email volume per organization
4. Consider email digests for non-urgent notifications

​

SMS Costs (Twilio)

• US/Canada: ~$0.0075 per SMS
• International: Varies by country
• MMS: Higher cost

1. Use SMS only for urgent notifications
2. Prefer email for non-urgent communications
3. Batch SMS when possible (future feature)
4. Monitor SMS volume per organization

​

Cost Monitoring

• Monitor provider dashboards for delivery volume, throttling, and failures
• Configure provider-side alerts/notifications for quota and auth issues

• Console shows usage and costs
• Set up spending limits

​

Error Handling

​

Email Errors

​

SMS Errors

• 400 - Invalid phone number
• 403 - Account suspended or insufficient credits
• 500 - Twilio service error

try {
  const response = await fetch(twilioUrl, { ... });
  if (!response.ok) {
    const errorData = await response.json();
    throw new Error(`Twilio API error: ${errorData.message}`);
  }
  return { success: true, messageSid: data.sid };
} catch (error) {
  // Log error, update notification status
  return { success: false, error: error.message };
}

​

Retry Logic

• No automatic retries
• Failed notifications marked as failed in database
• Manual retry via send-pending-notifications

• Automatic retry with exponential backoff
• Max 3 retries
• Alert on persistent failures

​

Testing

​

Test Email Delivery

// Test email function
const response = await fetch(
  'http://localhost:54321/functions/v1/send-email-notification',
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      notificationId: 'test-uuid',
      recipientEmail: 'test@example.com',
      subject: 'Test Email',
      body: 'This is a test email.',
    }),
  }
);

• Send to verified email addresses
• Check Supabase function logs and provider dashboards (Entra/Gmail) for delivery status

​

Test SMS Delivery

// Test SMS function
const response = await fetch(
  'http://localhost:54321/functions/v1/send-sms-notification',
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      notificationId: 'test-uuid',
      phoneNumber: '+1234567890',  // Verified number in trial
      message: 'Test SMS',
    }),
  }
);

• Use Twilio’s test credentials
• Send to verified phone numbers (trial)
• Check Twilio console for delivery status

​

Test Templates

const testVariables = {
  name: 'John Doe',
  action: 'approved',
  date: '2025-01-07',
  amount: '100.00',
};

// Verify all variables are replaced
const result = template.replace(/\{\{(\w+)\}\}/g, (match, key) => {
  return testVariables[key] || match;
});

​

Troubleshooting

​

Issue: Email Not Sending

• No email received
• Function returns success but no email

1. Entra: Verify ENTRA_CLIENT_SECRET and org Entra config (tenant, app, sender email). Check Graph consent includes Mail.Send.
2. Gmail: Verify GMAIL_SERVICE_ACCOUNT_JSON and org gmail_sender_email in Settings → Integrations → Gmail. Confirm domain-wide delegation for gmail.send.
3. Verify recipient email address is valid.
4. Check spam folder.
5. Review function logs in Supabase dashboard.

​

Issue: SMS Not Sending

• No SMS received
• Function returns error

1. Check Twilio credentials are set correctly
2. Verify phone number format: +1234567890
3. Check Twilio account has credits
4. Verify phone number is verified (trial account)
5. Check Twilio console for delivery status
6. Review function logs in Supabase dashboard

​

Issue: Template Variables Not Replaced

• Email/SMS contains {{variable}} literally

1. Verify variables object includes all template variables
2. Check variable names match exactly (case-sensitive)
3. Verify template syntax: {{variable_name}}
4. Check function logs for variable replacement

​

Issue: Rate Limit Exceeded

• 429 errors from email provider or Twilio
• Notifications fail

1. Implement rate limiting in application
2. Batch notifications when possible
3. For Entra/Gmail, check tenant or Google project quotas
4. Use send-pending-notifications for batch processing
5. Add retry logic with backoff

​

Issue: High Costs

• Unexpected charges from Twilio (or cloud provider)

1. Monitor usage in provider dashboards
2. Implement rate limiting per organization
3. Use email digests for non-urgent notifications
4. Prefer email over SMS when possible
5. Set spending limits in Twilio console

​

Best Practices

​

1. Email Best Practices

• Use verified domains (Entra: org mailbox; Gmail: Workspace domain)
• Set up SPF/DKIM/DMARC per your domain
• Monitor bounce rates and handle bounces
• Use templates for consistency
• Test templates before production use
• Monitor delivery via Supabase logs and provider dashboards (Graph / Gmail)

​

2. SMS Best Practices

• Use SMS only for urgent notifications
• Keep messages concise (< 160 characters)
• Include opt-out instructions (if required)
• Verify phone numbers before sending
• Monitor delivery rates in Twilio console
• Handle failed deliveries gracefully

​

3. Security

• Never log full email addresses or phone numbers
• Sanitize user input in templates
• Validate email/phone formats before sending
• Use HTTPS for all API calls
• Rotate API keys regularly
• Monitor for abuse (unusual sending patterns)

​

Related Documentation

• Edge Functions: docs/integrations/EDGE_FUNCTIONS.md
• Environment Variables: docs/development/ENVIRONMENT_VARIABLES.md
• Secrets Management: docs/security/SECRETS_MANAGEMENT.md
• Notifications: specs/pf/specs/PF-10-notification-system.md