Skip to main content

Email Templates - Supabase Authentication

What Are Email Templates?​

Email templates are the HTML emails sent by Supabase Auth for authentication flows:

  • Confirmation Email: Sent when a new user signs up
  • Password Reset: Sent when a user requests password reset
  • Magic Link: Sent for passwordless authentication
  • Email Change: Sent when a user updates their email address
  • Invitation: Sent when inviting users to your application
  • Reauthentication: Sent when user needs to verify identity

Component: Supabase Auth​

Location: services/supabase/email-templates/ Managed By: Supabase Auth service (backend) Deployed To: Supabase platform (not self-hosted)

Template Files​

services/supabase/email-templates/
├── confirmation.html         # Email verification
├── reset-password.html        # Password reset
├── magic-link.html           # Passwordless login
├── change-email.html         # Email change confirmation
├── invite.html               # User invitation
└── reauthentication.html     # Identity verification

How Templates Are Used​

1. User Triggers Action​

User → Sign Up → Supabase Auth → Sends "confirmation.html" email
User → Forgot Password → Supabase Auth → Sends "reset-password.html" email

2. Template Processing​

Supabase Auth injects dynamic variables into templates:

  • {{ .ConfirmationURL }} - Login/confirmation link
  • {{ .Token }} - Verification token
  • {{ .TokenHash }} - Hashed token
  • {{ .SiteURL }} - Your application URL
  • {{ .Email }} - User's email address

3. Email Delivery​

Supabase sends emails via their SMTP service (or your configured SMTP).

Deployment Process​

Current Setup (Automated)​

Templates are primarily managed in the codebase and deployed automatically via the CI/CD pipeline.

What the Script Does​

  1. Reads all .html files from email-templates/
  2. Uses Supabase Management API to update Auth configuration
  3. Updates subject lines and HTML content
  4. Applies changes to the specified project (sandbox or prod)

Automated Deployment (New)​

Now integrated into CI/CD workflow (_supabase.yml):

- name: Deploy Email Templates
  working-directory: services/supabase
  env:
    SUPABASE_ACCESS_TOKEN: ${{ secrets.SUPABASE_ACCESS_TOKEN }}
  run: |
    echo "📧 Deploying email templates to ${{ inputs.environment }}..."
    node scripts/deploy-email-templates.js ${{ secrets.SUPABASE_PROJECT_REF }}

Triggers: Automatically when you push changes to services/supabase/**

Template Customization​

Brand Colors & Styling​

Templates use inline CSS for email client compatibility:

<!-- Primary brand color -->
<div style="background-color: #3B82F6; padding: 24px;">
  <!-- Button styling -->
  <a
    href="{{ .ConfirmationURL }}"
    style="
  background-color: #3B82F6;
  color: white;
  padding: 12px 24px;
  text-decoration: none;
  border-radius: 6px;
  "
  >
    Confirm Email
  </a>
</div>

Available Variables​

VariableDescriptionExample
{{ .ConfirmationURL }}Action link (confirm, reset, login)https://yourapp.com/auth/callback?token=...
{{ .Token }}Verification tokenabc123...
{{ .TokenHash }}Hashed tokendef456...
{{ .SiteURL }}Your application URLhttps://freeaihashtags.com
{{ .Email }}User's email addressuser@example.com
{{ .RedirectTo }}Optional redirect parameter/dashboard

Testing Templates​

To test changes to templates:

  1. Update HTML files in services/supabase/email-templates/.
  2. Push changes to the sandbox branch.
  3. Trigger an email action in the Sandbox environment (e.g., sign up a test user).
  4. Verify styling and links in the received email.

Why Templates Are Not in Supabase Studio​

Storage Location: Templates are stored in Supabase's Auth configuration, not as database records or static files.

Access Method: Must use the Supabase Management API to update them (which the script does).

No GUI: Supabase Studio doesn't provide a template editor yet, so we manage them via code + API.

Email Template Best Practices​

1. Subject Lines​

Keep them clear and action-oriented:

{
  subject: "Confirm your email address", // ✅ Good
  subject: "Welcome!",                    // ❌ Vague
}

2. Mobile Responsiveness​

Use responsive design patterns:

<table width="100%" cellpadding="0" cellspacing="0">
  <tr>
    <td style="max-width: 600px; margin: 0 auto;">
      <!-- Content here -->
    </td>
  </tr>
</table>

3. Clear Call-to-Action​

Make buttons prominent:

<a
  href="{{ .ConfirmationURL }}"
  style="
  display: inline-block;
  background-color: #3B82F6;
  color: white;
  font-weight: bold;
  padding: 14px 28px;
  text-decoration: none;
  border-radius: 8px;
  "
>
  Confirm My Email →
</a>

4. Fallback Text Link​

Always include a text link for email clients that block buttons:

<p style="color: #6B7280; font-size: 14px;">
  If the button doesn't work, copy this link:<br />
  <a href="{{ .ConfirmationURL }}">{{ .ConfirmationURL }}</a>
</p>

Troubleshooting​

Templates Not Updating​

Symptom: Changes to HTML files not reflected in emails

Solution:

# Redeploy templates
cd services/supabase
node scripts/deploy-email-templates.js <project-ref>

Emails Not Sending​

Symptom: Users not receiving emails

Check:

  1. Supabase Dashboard → Authentication → Email Templates → SMTP Settings
  2. Verify EMAIL_PROVIDER is configured
  3. Check spam folder
  4. Check Supabase logs: Dashboard → Logs → Select "Auth"

Symptom: Confirmation links don't work

Check:

  1. SITE_URL in Supabase Dashboard → Settings → API
  2. Verify redirect URLs in Dashboard → Authentication → URL Configuration
  3. Ensure {{ .ConfirmationURL }} is used correctly in template

CI/CD Integration​

Automatic Deployment​

When you push to sandbox or main branch with changes in services/supabase/:

  1. GitHub Actions triggers
  2. Supabase CLI deploys migrations
  3. Supabase CLI deploys Edge Functions
  4. Node script deploys email templates ← New!
  5. Verification step confirms success

Deployment​

Deployment is strictly automated via GitHub Actions on push to sandbox or main.