Charchy Senddocs

Supabase Auth emails

Send Supabase Auth's sign-up, magic link, recovery, invite, email change and reauthentication emails through Charchy Send with the Send Email Hook — an Edge Function, no SMTP.

Supabase Auth's Send Email Hook calls an HTTPS endpoint instead of sending its emails itself. Point it at an Edge Function that calls Charchy Send.

1. The Edge Function

supabase/functions/send-email/index.ts
import { CharchySend, type SendEmailParams } from "npm:@charchy/send@0"
import { Webhook } from "npm:standardwebhooks@1"

// The hook secret is "v1,whsec_<base64>"; standardwebhooks wants the base64 part.
const hook = new Webhook(Deno.env.get("SEND_EMAIL_HOOK_SECRET")!.replace("v1,whsec_", ""))
// Supabase gives the whole hook 5 seconds, retries included.
const send = new CharchySend(Deno.env.get("CHARCHY_SEND_KEY"), { maxRetries: 1, timeoutMs: 2_000 })
const from = Deno.env.get("CHARCHY_SEND_FROM")!
const verifyUrl = `${Deno.env.get("SUPABASE_URL")}/auth/v1/verify`

type HookPayload = {
  user: { email: string; new_email?: string }
  email_data: {
    token: string
    token_hash: string
    redirect_to: string
    email_action_type: string
    site_url: string
    token_new: string
    token_hash_new: string
  }
}

const SUBJECTS: Record<string, string> = {
  signup: "Confirm your email",
  magiclink: "Your sign-in link",
  recovery: "Reset your password",
  invite: "You've been invited",
  email_change: "Confirm your email change",
  reauthentication: "Your verification code",
}

Deno.serve(async (request) => {
  const payload = await request.text() // the raw body
  let user: HookPayload["user"]
  let data: HookPayload["email_data"]
  try {
    ;({ user, email_data: data } = hook.verify(payload, Object.fromEntries(request.headers)) as HookPayload)
  } catch {
    return Response.json({ error: { http_code: 401, message: "Invalid signature" } }, { status: 401 })
  }

  const action = data.email_action_type
  const subject = SUBJECTS[action] ?? "Your account was updated"
  const emails: { to: string; token: string; tokenHash: string }[] =
    // Secure email change: two emails. The names are swapped on purpose (Supabase keeps them for
    // backward compatibility): token_hash_new goes to the CURRENT address with token.
    action === "email_change" && data.token_hash_new && user.new_email
      ? [
          { to: user.email, token: data.token, tokenHash: data.token_hash_new },
          { to: user.new_email, token: data.token_new, tokenHash: data.token_hash },
        ]
      : action === "email_change"
        ? [{ to: user.new_email ?? user.email, token: data.token || data.token_new, tokenHash: data.token_hash }]
        : [{ to: user.email, token: data.token, tokenHash: data.token_hash }]

  for (const email of emails) {
    const result = await send.emails.send(
      { from, to: email.to, subject, ...body(action, email.token, email.tokenHash, data.redirect_to), tags: { type: `supabase_${action}` } },
      // Stable across Supabase's retries of the same hook call.
      { idempotencyKey: `supabase/${action}/${email.tokenHash || request.headers.get("webhook-id")}/${email.to}` }
    )
    if (result.error) {
      const retry = result.error.statusCode === null || result.error.statusCode >= 500 || result.error.statusCode === 429
      return Response.json(
        { error: { http_code: retry ? 503 : 500, message: `Charchy Send ${result.error.code}` } },
        { status: retry ? 503 : 500, headers: retry ? { "retry-after": "1" } : {} }
      )
    }
  }
  return Response.json({})
})

function body(action: string, token: string, tokenHash: string, redirectTo: string): Pick<SendEmailParams, "text" | "html"> {
  if (!tokenHash) {
    // reauthentication carries a code only; *_notification types carry neither.
    return token
      ? { text: `Your code is ${token}.`, html: `<p>Your code is <strong>${token}</strong>.</p>` }
      : { text: "Your account was updated. If this wasn't you, contact us.", html: "<p>Your account was updated. If this wasn't you, contact us.</p>" }
  }
  const link = `${verifyUrl}?token=${tokenHash}&type=${action}&redirect_to=${encodeURIComponent(redirectTo)}`
  return {
    text: `${SUBJECTS[action] ?? "Continue"}: ${link}\n\nOr enter this code: ${token}`,
    html: `<p><a href="${link}">${SUBJECTS[action] ?? "Continue"}</a></p><p>Or enter this code: <strong>${token}</strong></p>`,
  }
}
  • Signature. Supabase signs the hook with Standard Webhooks (webhook-id, webhook-timestamp, webhook-signature). Its secret has a v1,whsec_ prefix; the standardwebhooks library takes the base64 part after it.
  • Answers. An empty 200 means sent. 503 with retry-after makes Supabase retry; it gives the hook 5 seconds in all, which is why the client gets one retry and a 2-second timeout.
  • Email change. With Secure Email Change on, one call carries two codes: token with token_hash_new for the current address, token_new with token_hash for the new one — the names are reversed in Supabase's payload. With it off, one email goes to the new address.
  • Notifications. The hook can also receive security notices (password_changed_notification and the other *_notification types). They carry no link, so the function sends a plain notice; give each its own wording if you use them.

2. Secrets and deploy

supabase secrets set CHARCHY_SEND_KEY=chy_test_… CHARCHY_SEND_FROM="My App <no-reply@myapp.com>"
supabase functions deploy send-email --no-verify-jwt

--no-verify-jwt: Supabase Auth signs the call with the hook's secret, not a user's token — the signature check protects the function. SUPABASE_URL is already set in every Edge Function.

3. Turn the hook on

In the Supabase dashboard, Authentication → Hooks: add a Send Email hook of type HTTPS with your function's URL, and generate its secret. Set it on the function:

supabase secrets set SEND_EMAIL_HOOK_SECRET="v1,whsec_…"

Sign up as delivered@sim.charchy.krd and the email shows on the Charchy dashboard's Emails page.

On this page