Send Email Hook Setup Guide

Overview

This Send Email Hook replaces Supabase’s default email templates with SendGrid’s dynamic templates, providing platform-specific email handling for mobile and web applications.

Features

Platform detection (mobile vs web)
SendGrid dynamic templates
Conditional email content (code-only for mobile, link-only for web)
Support for all 6 Supabase auth email types: signup, recovery, magic link, email change, invite, and reauthenticate emails

Setup Steps

1. Environment Variables

Add these environment variables to your Supabase project:

# SendGrid API Key
SENDGRID_API_KEY=your_sendgrid_api_key_here

# Hook secret (generate in Supabase Dashboard > Auth > Hooks)
SEND_EMAIL_HOOK_SECRET=v1,whsec_your_base64_secret_here

# Supabase Anonymous Key (already available in your environment)
SUPABASE_ANON_KEY=your_supabase_anon_key_here

2. SendGrid Template IDs

The current template IDs configured in the system:

const SENDGRID_TEMPLATES = {
  signup: "d-f616cf918fea42b2ac48870b0953154b", // Confirm signup
  recovery: "d-4264768063af464bb138244a4cfc011e", // Reset password
  magiclink: "d-615be9bd4d34493f80a7c7ba283516a3", // Magic link login
  email_change: "d-your-email-change-template-id", // TODO: Configure email change template
  invite: "d-6f15a805896e468fb8ad74cb69d62c5f", // Invite user
  reauthenticate: "d-your-reauthenticate-template-id", // TODO: Configure reauthenticate template
};

Note: The email_change and reauthenticate templates still need to be configured with actual SendGrid template IDs.

3. SendGrid Dynamic Template Setup

Create dynamic templates in SendGrid with these variables:

Available Variables for Templates

Common Variables (Available in All Templates):

{{first_name}}
<!-- User's first name (only present if available) -->
{{email}}
<!-- User's email address -->
{{platform}}
<!-- "mobile" or "web" -->
{{token}}
<!-- 6-digit OTP code -->
{{confirmation_url}}
<!-- Full confirmation URL with /auth/v1/verify endpoint -->
{{site_url}}
<!-- Base site URL -->
{{action_type}}
<!-- Email action type -->
{{subject}}
<!-- Email subject line -->

Template-Specific Variables:

Signup Template (d-f616cf918fea42b2ac48870b0953154b)
- {{subject}} → “Confirm Your Signup - ADHD Simple”
Recovery Template (d-4264768063af464bb138244a4cfc011e)
- {{subject}} → “Reset Your Password - ADHD Simple”
Magic Link Template (d-615be9bd4d34493f80a7c7ba283516a3)
- {{subject}} → “Magic Link Login - ADHD Simple”
Invite Template (d-6f15a805896e468fb8ad74cb69d62c5f)
- {{subject}} → “You’ve Been Invited - ADHD Simple”
Email Change Template (TODO)
- {{subject}} → “Confirm Email Change - ADHD Simple”
- {{new_email}} → New email address (if applicable)
Reauthenticate Template (TODO)
- {{subject}} → “Security Verification Required - ADHD Simple”

Platform Detection:

{{platform}} will be “mobile” or “web”
Use {{#equals platform "mobile"}} for conditional content in SendGrid templates
Use {{#if first_name}} for checking if variables exist

Template Examples

Signup Template:

<h2>{{subject}}</h2>

<p>Hi {{#if first_name}}{{first_name}}{{else}}there{{/if}},</p>

{{#equals platform "mobile"}}
  <!-- Mobile: Show code only -->
  <p style="font-size: 16px; margin-bottom: 10px; color: #333;">Enter this code
    in the app:</p>
  <div
    style="font-size: 32px; font-weight: bold; text-align: center; color: #3C93CD; letter-spacing: 4px; font-family: 'Courier New', monospace; padding: 20px; background: #f8f9fa; border: 2px solid #3C93CD; border-radius: 8px;"
  >
    {{token}}
  </div>
  <p style="font-size: 14px; color: #666; margin-top: 10px;">This code expires
    in 1 hour.</p>
{{else}}
  <!-- Web: Show button with link -->
  <p>Follow this link to confirm your signup:</p>
  <div style="text-align: center; margin: 20px 0;">
    <a
      href="{{confirmation_url}}"
      style="background-color: #3C93CD; color: white; padding: 12px 44px; text-decoration: none; border-radius: 100px; font-weight: bold; letter-spacing: 1px; display: inline-block;"
    >
      VERIFY EMAIL
    </a>
  </div>
{{/equals}}

<p>Welcome to ADHD Simple!</p>

Recovery Template:

<h2>{{subject}}</h2>

<p>Hi {{#if first_name}}{{first_name}}{{else}}there{{/if}},</p>

{{#equals platform "mobile"}}
  <!-- Mobile: Show code only -->
  <p style="font-size: 16px; margin-bottom: 10px; color: #333;">Enter this code
    in the app to reset your password:</p>
  <div
    style="font-size: 32px; font-weight: bold; text-align: center; color: #ff9800; letter-spacing: 4px; font-family: 'Courier New', monospace; padding: 20px; background: #f8f9fa; border: 2px solid #ff9800; border-radius: 8px;"
  >
    {{token}}
  </div>
  <p style="font-size: 14px; color: #666; margin-top: 10px;">This code expires
    in 1 hour.</p>
{{else}}
  <!-- Web: Show button with link -->
  <p>Click this link to reset your password:</p>
  <div style="text-align: center; margin: 20px 0;">
    <a
      href="{{confirmation_url}}"
      style="background-color: #ff9800; color: white; padding: 12px 44px; text-decoration: none; border-radius: 100px; font-weight: bold; letter-spacing: 1px; display: inline-block;"
    >
      RESET PASSWORD
    </a>
  </div>
{{/equals}}

Magic Link Template:

<h2>{{subject}}</h2>

<p>Hi {{#if first_name}}{{first_name}}{{else}}there{{/if}},</p>

{{#equals platform "mobile"}}
  <!-- Mobile: Show code only -->
  <p style="font-size: 16px; margin-bottom: 10px; color: #333;">Use this code to
    sign in to the app:</p>
  <div
    style="font-size: 32px; font-weight: bold; text-align: center; color: #2196f3; letter-spacing: 4px; font-family: 'Courier New', monospace; padding: 20px; background: #f8f9fa; border: 2px solid #2196f3; border-radius: 8px;"
  >
    {{token}}
  </div>
  <p style="font-size: 14px; color: #666; margin-top: 10px;">This code expires
    in 1 hour.</p>
{{else}}
  <!-- Web: Show button with link -->
  <p>Click this magic link to sign in:</p>
  <div style="text-align: center; margin: 20px 0;">
    <a
      href="{{confirmation_url}}"
      style="background-color: #2196f3; color: white; padding: 12px 44px; text-decoration: none; border-radius: 100px; font-weight: bold; letter-spacing: 1px; display: inline-block;"
    >
      SIGN IN
    </a>
  </div>
{{/equals}}

Invite Template:

<h2>{{subject}}</h2>

<p>Hi {{#if first_name}}{{first_name}}{{else}}there{{/if}},</p>

{{#equals platform "mobile"}}
  <!-- Mobile: Show code only -->
  <p style="font-size: 16px; margin-bottom: 10px; color: #333;">You've been
    invited to join ADHD Simple! Use this code in the mobile app:</p>
  <div
    style="font-size: 32px; font-weight: bold; text-align: center; color: #9c27b0; letter-spacing: 4px; font-family: 'Courier New', monospace; padding: 20px; background: #f8f9fa; border: 2px solid #9c27b0; border-radius: 8px;"
  >
    {{token}}
  </div>
  <p style="font-size: 14px; color: #666; margin-top: 10px;">This code expires
    in 1 hour.</p>
{{else}}
  <!-- Web: Show button with link -->
  <p>You've been invited to join ADHD Simple! Click to accept:</p>
  <div style="text-align: center; margin: 20px 0;">
    <a
      href="{{confirmation_url}}"
      style="background-color: #9c27b0; color: white; padding: 12px 44px; text-decoration: none; border-radius: 100px; font-weight: bold; letter-spacing: 1px; display: inline-block;"
    >
      ACCEPT INVITATION
    </a>
  </div>
{{/equals}}

4. Deploy the Function

# Set environment variables in Supabase
supabase secrets set SENDGRID_API_KEY=your_key_here
supabase secrets set SEND_EMAIL_HOOK_SECRET=your_secret_here

# Deploy the function
supabase functions deploy send-email --no-verify-jwt

5. Configure Auth Hook

Go to Supabase Dashboard > Auth > Hooks
Create a new “Send Email” hook
Set the URL to: https://your-project-id.supabase.co/functions/v1/send-email
Generate and copy the hook secret to your environment variables (format: v1,whsec_base64_secret)

6. Platform Detection Logic

The hook determines platform based on (in priority order):

User metadata: user.user_metadata.platform === "mobile"
App metadata: user.app_metadata.platform === "mobile"
Redirect URL patterns:
- Mobile indicators: adhdsimple://, exp://, /mobile/, app.adhdsimple.co.uk
- Default: web

7. URL Construction

The confirmation URLs are built with the correct Supabase auth endpoint:

https://your-project-id.supabase.co/auth/v1/verify?token=TOKEN_HASH&type=EMAIL_TYPE&redirect_to=ENCODED_REDIRECT_URL

Important: No apikey parameter is needed - Supabase handles this internally.

8. Testing

Test different email types:

# Signup
curl -X POST 'https://your-project-id.supabase.co/auth/v1/signup' \
  -H 'apikey: your-anon-key' \
  -H 'Content-Type: application/json' \
  -d '{"email": "test@example.com", "password": "password123"}'

# Recovery
curl -X POST 'https://your-project-id.supabase.co/auth/v1/recover' \
  -H 'apikey: your-anon-key' \
  -H 'Content-Type: application/json' \
  -d '{"email": "test@example.com"}'

# Magic Link
curl -X POST 'https://your-project-id.supabase.co/auth/v1/magiclink' \
  -H 'apikey: your-anon-key' \
  -H 'Content-Type: application/json' \
  -d '{"email": "test@example.com"}'

# Invite User (requires service role key)
curl -X POST 'https://your-project-id.supabase.co/auth/v1/invite' \
  -H 'apikey: your-service-role-key' \
  -H 'Content-Type: application/json' \
  -d '{"email": "test@example.com"}'

Platform-Specific Behavior

Mobile Apps

Shows only the 6-digit verification code
Code expires in 1 hour
No clickable links (users enter code manually)
Platform detected via user metadata or redirect URL patterns

Web Apps

Shows only confirmation button/link
No verification code displayed
Standard email confirmation flow with clickable links
Users are redirected after clicking the link

Troubleshooting

Common Issues

“No API key found in request” error:
- Fixed by ensuring URL uses /auth/v1/verify endpoint (not /auth/v1)
- No apikey parameter needed in the URL
Hook secret format: Must start with v1,whsec_
Template IDs: Must start with d- and be valid SendGrid dynamic template IDs
Platform detection: Check user metadata and redirect URL patterns
SendGrid templates: Ensure Handlebars syntax is correct (use {{#equals platform "mobile"}} for comparisons, {{#if first_name}} for existence checks)

Logs

Check function logs:

supabase functions logs send-email --follow

Testing Platform Detection

Set platform explicitly in user metadata:

// Mobile signup
supabase.auth.signUp({
  email: "test@example.com",
  password: "password123",
  options: {
    data: {
      platform: "mobile",
    },
  },
});

// Web signup (default)
supabase.auth.signUp({
  email: "test@example.com",
  password: "password123",
});

Configuration Status

✅ Configured and Working:

Signup emails
Recovery emails
Magic link emails
Invite emails

⚠️ Needs Configuration:

Email change emails (template ID needed)
Reauthenticate emails (template ID needed)

Next Steps

Create SendGrid templates for email_change and reauthenticate actions
Update the template IDs in packages/supabase/functions/send-email/index.ts
Test all email flows in both mobile and web contexts
Monitor function logs for any issues

Getting Started

User Guides - Clinical

User Guides - Pharmacy

User Guides - Mobile

Technical Documentation - General

Technical Documentation - Mobile

Documentation Standards

Security

Architecture

Send email hook setup

Send Email Hook Setup Guide

Overview

Features

Setup Steps

1. Environment Variables

2. SendGrid Template IDs

3. SendGrid Dynamic Template Setup

Available Variables for Templates

Template Examples

4. Deploy the Function

5. Configure Auth Hook

6. Platform Detection Logic

7. URL Construction

8. Testing

Platform-Specific Behavior

Mobile Apps

Web Apps

Troubleshooting

Common Issues

Logs

Testing Platform Detection

Configuration Status

Next Steps

​Send Email Hook Setup Guide

​Overview

​Features

​Setup Steps

​1. Environment Variables

​2. SendGrid Template IDs

​3. SendGrid Dynamic Template Setup

​Available Variables for Templates

​Template Examples

​4. Deploy the Function

​5. Configure Auth Hook

​6. Platform Detection Logic

​7. URL Construction

​8. Testing

​Platform-Specific Behavior

​Mobile Apps

​Web Apps

​Troubleshooting

​Common Issues

​Logs

​Testing Platform Detection

​Configuration Status

​Next Steps

Send Email Hook Setup Guide

Overview

Features

Setup Steps

1. Environment Variables

2. SendGrid Template IDs

3. SendGrid Dynamic Template Setup

Available Variables for Templates

Template Examples

4. Deploy the Function

5. Configure Auth Hook

6. Platform Detection Logic

7. URL Construction

8. Testing

Platform-Specific Behavior

Mobile Apps

Web Apps

Troubleshooting

Common Issues

Logs

Testing Platform Detection

Configuration Status

Next Steps