Encore OS — Documentation

Version: 1.1.0
Last Updated: 2026-03-11 This guide documents how to configure email and SMS notification services for the Encore OS Platform.

Overview
Email Service (Entra ID & Gmail)
SMS Service (RingCentral)
Template Configuration
Rate Limiting & Quotas
Cost Optimization
Error Handling
Testing
Troubleshooting

Overview

Encore OS uses external services for email and SMS delivery:

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

Email is sent via the shared email-provider abstraction used by:

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)

Org-level email supports two providers. Choose one per organization in HR → Settings → Email Provider (and optionally set a fallback).

Microsoft Entra ID (recommended)

Configure the Entra ID integration in Settings → Integrations → Microsoft Entra ID (tenant, app registration, admin consent with Mail.Send).

Set the sender email in the same page (or in pf_organizations.settings.entra_sender_email).

Set ENTRA_CLIENT_SECRET in Supabase secrets (client secret for the app registration).

In HR → Settings → Email, select Microsoft Entra ID and optionally set From Email Address / From Name.

If Entra is selected but fails (e.g. token issue), the system can fall back to Gmail when Gmail is configured for the org.

Gmail (Google Workspace)

Google Cloud: Create a project, enable Gmail API, create a service account.

Domain-wide delegation: In Google Workspace Admin, grant the service account domain-wide delegation for scope https://www.googleapis.com/auth/gmail.send.

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",...}'

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.

In HR → Settings → Email, select Gmail (Google Workspace) and optionally set From Email Address / From Name.

Required secret: GMAIL_SERVICE_ACCOUNT_JSON (full JSON key for the service account). Edge functions: All email senders use supabase/functions/_shared/email-provider.ts; no separate provider-specific integration is required beyond Entra/Gmail configuration.

SMS Service (RingCentral)

1. Create a RingCentral App

Go to the RingCentral Developer Console

Create an app with SMS permissions (and JWT auth credential)

Note your environment (Production vs Sandbox)

2. Get Credentials

Client ID / Client Secret:

Open your app → Credentials
Copy the Client ID and Client Secret

JWT Credential:

Go to Credentials → JWT

Create a JWT credential scoped to the app

Copy the JWT token

SMS-enabled phone number:

Provision an SMS-enabled number on your RingCentral account

Configure it per-org in CE Settings → SMS (ringcentral_sms_phone_number)

3. Set Supabase Secrets

# Set RingCentral credentials
supabase secrets set RINGCENTRAL_CLIENT_ID=xxxxx
supabase secrets set RINGCENTRAL_CLIENT_SECRET=xxxxx
supabase secrets set RINGCENTRAL_JWT_TOKEN=xxxxx

# Verify secrets are set
supabase secrets list

4. Configure Edge Function

Edge Function: sms-send Required Secrets:

RINGCENTRAL_CLIENT_ID
RINGCENTRAL_CLIENT_SECRET
RINGCENTRAL_JWT_TOKEN

Function Location: supabase/functions/sms-send/index.ts

Template Configuration

Email Templates

Template Variables:

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

Example Template:

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

Usage in Code:

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

Message Limits:

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

Example Template:

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

Usage in Code:

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

Microsoft Graph (Entra): Throttling and quotas apply per tenant; see Microsoft documentation. Gmail API: Quotas and sending limits apply per Google Cloud project and per user; see Google documentation.

RingCentral Limits

Sandbox Account:

Limited to numbers on the developer account
SMS only to allowed numbers

Production Account:

Subject to your RingCentral plan’s SMS allotment
Pay/throttle per plan terms

Rate Limits:

RingCentral enforces per-app/per-extension SMS rate limits
Throttling may occur at high volumes

Platform Limits

Encore OS Rate Limiting (Planned):

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

Current Status: Rate limiting not yet implemented

Cost Optimization

Email Costs (Entra / Gmail)

Entra: Included with Microsoft 365 licensing; Graph API usage subject to tenant limits. Gmail: Subject to Google Workspace and Gmail API quotas; no per-message fee for typical org usage. Optimization Tips:

Batch notifications when possible

Use send-pending-notifications for batch processing

Monitor email volume per organization

Consider email digests for non-urgent notifications

SMS Costs (RingCentral)

Pricing:

Included in your RingCentral plan’s SMS allotment; overage billed per RingCentral terms
International: Varies by country
MMS: Higher cost

Optimization Tips:

Use SMS only for urgent notifications

Prefer email for non-urgent communications

Batch SMS when possible (future feature)

Monitor SMS volume per organization

Cost Monitoring

Email providers (Entra/Gmail):

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

RingCentral:

Admin console / analytics shows SMS usage
Monitor plan allotment and overage

Error Handling

Email Errors

Entra (Graph API): 4xx/5xx from Graph; check tenant, app permissions, and sender identity. Gmail API: 4xx/5xx from Gmail; check service account, domain-wide delegation, and sender email. Error Handling: The shared email-provider returns EmailSendResult with success and errorMessage; callers update notification status and log accordingly.

SMS Errors

Common Error Codes:

400 - Invalid phone number
403 - Account suspended or insufficient permissions
500 - RingCentral service error

Error Handling in Function:

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

Retry Logic

Current Implementation:

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

Future Enhancement:

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

Testing

Test Email Delivery

Development:

// 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.',
    }),
  }
);

Production:

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

Test SMS Delivery

Development:

// 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',
    }),
  }
);

Production:

Use a RingCentral sandbox app for testing
Send to allowed phone numbers (sandbox)
Check the RingCentral console for delivery status

Test Templates

Test Template Variables:

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

Symptoms:

No email received
Function returns success but no email

Solutions:

Entra: Verify ENTRA_CLIENT_SECRET and org Entra config (tenant, app, sender email). Check Graph consent includes Mail.Send.

Gmail: Verify GMAIL_SERVICE_ACCOUNT_JSON and org gmail_sender_email in Settings → Integrations → Gmail. Confirm domain-wide delegation for gmail.send.

Verify recipient email address is valid.

Check spam folder.

Review function logs in Supabase dashboard.

Issue: SMS Not Sending

Symptoms:

No SMS received
Function returns error

Solutions:

Check RingCentral credentials are set correctly

Verify phone number format: +1234567890

Check the RingCentral app has SMS permissions/allotment

Verify the number is allowed (sandbox account)

Check the RingCentral console for delivery status

Review function logs in Supabase dashboard

Issue: Template Variables Not Replaced

Symptoms:

Email/SMS contains {{variable}} literally

Solutions:

Verify variables object includes all template variables

Check variable names match exactly (case-sensitive)

Verify template syntax: {{variable_name}}

Check function logs for variable replacement

Issue: Rate Limit Exceeded

Symptoms:

429 errors from email provider or RingCentral
Notifications fail

Solutions:

Implement rate limiting in application

Batch notifications when possible

For Entra/Gmail, check tenant or Google project quotas

Use send-pending-notifications for batch processing

Add retry logic with backoff

Issue: High Costs

Symptoms:

Unexpected charges from RingCentral (or cloud provider)

Solutions:

Monitor usage in provider dashboards

Implement rate limiting per organization

Use email digests for non-urgent notifications

Prefer email over SMS when possible

Monitor SMS allotment in the RingCentral 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 the RingCentral 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)

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

Document Owner: Platform Team
Review Frequency: Quarterly
Last Updated: 2025-01-07

​Table of Contents

​Overview

​Email Service (Entra ID & Gmail)

​Microsoft Entra ID (recommended)

​Gmail (Google Workspace)

​SMS Service (RingCentral)

​1. Create a RingCentral App

​2. Get Credentials

​3. Set Supabase Secrets

​4. Configure Edge Function

​Template Configuration

​Email Templates

​SMS Templates

​Rate Limiting & Quotas

​Email (Entra / Gmail) Limits

​RingCentral Limits

​Platform Limits

​Cost Optimization

​Email Costs (Entra / Gmail)

​SMS Costs (RingCentral)

​Cost Monitoring

​Error Handling

​Email Errors

​SMS Errors

​Retry Logic

​Testing

​Test Email Delivery

​Test SMS Delivery

​Test Templates

​Troubleshooting

​Issue: Email Not Sending

​Issue: SMS Not Sending

​Issue: Template Variables Not Replaced

​Issue: Rate Limit Exceeded

​Issue: High Costs

​Best Practices

​1. Email Best Practices

​2. SMS Best Practices

​3. Security

​Related Documentation

Table of Contents

Overview

Email Service (Entra ID & Gmail)

Microsoft Entra ID (recommended)

Gmail (Google Workspace)

SMS Service (RingCentral)

1. Create a RingCentral App

2. Get Credentials

3. Set Supabase Secrets

4. Configure Edge Function

Template Configuration

Email Templates

SMS Templates

Rate Limiting & Quotas

Email (Entra / Gmail) Limits

RingCentral Limits

Platform Limits

Cost Optimization

Email Costs (Entra / Gmail)

SMS Costs (RingCentral)

Cost Monitoring

Error Handling

Email Errors

SMS Errors

Retry Logic

Testing

Test Email Delivery

Test SMS Delivery

Test Templates

Troubleshooting

Issue: Email Not Sending

Issue: SMS Not Sending

Issue: Template Variables Not Replaced

Issue: Rate Limit Exceeded

Issue: High Costs

Best Practices

1. Email Best Practices

2. SMS Best Practices

3. Security

Related Documentation