How to send Supabase emails with custom SMTP, the Send Email Hook and Edge Functions
Supabase sends 2 auth emails per hour until you plug in your own provider. Set up custom SMTP, the Send Email Hook, or an Edge Function, with code you can deploy.
Your Supabase project sends its first confirmation emails without any setup. Then the first real user signs up and gets nothing: the built-in sender only delivers to your project's team members, and only 2 emails per hour (Supabase custom SMTP docs). Supabase's production checklist lists your own SMTP credentials among the things to do before going public.
This guide shows how to send Supabase emails through Nuntly, an email API with an SMTP relay, in the order you'll need it: custom SMTP for auth emails, the Send Email Hook when you want your own templates, Edge Functions for app emails, then self-hosted Supabase. Every Supabase limit and behavior below links its source and was checked on November 14, 2026.
Why Supabase stops sending your emails
The default SMTP server is there to try Supabase Auth, not to run an app. Supabase's custom SMTP page lists three restrictions:
- Team-only recipients. Addresses outside the project's team fail with
Email address not authorized. - 2 messages per hour for the whole project, a value Supabase says can change without notice. The rate limits page gives the same figure.
- No SLA on delivery or uptime.
Every flow that emails a user goes through this sender: sign-up confirmation, magic links and one-time codes, invitations, password resets and email changes.
Pick a method
| Method | Who writes the email | Use it for |
|---|---|---|
| Custom SMTP | Supabase templates | Auth emails, no code to deploy |
| Send Email Hook | Your Edge Function | Auth emails with your own templates, languages or logic |
| Edge Function | Your Edge Function | App emails: receipts, notifications |
| Self-hosted SMTP | Supabase templates | Auth emails on your own Supabase instance |
Custom SMTP and the hook both handle auth emails, and they don't run together:
The Send Email Hook replaces Supabase's built-in email sending.
Source: Supabase Send Email Hook docs, read on November 14, 2026
With the hook on, Supabase skips SMTP for every auth email. Start with SMTP; move to the hook when the dashboard templates stop being enough.
Before you start
You need two things in Nuntly:
- A verified sending domain. Supabase sends from an address on it, such as
auth@mail.example.com. Add a sending domain walks through the DKIM, SPF and DMARC records, and SPF, DKIM, and DMARC explained covers what each one checks. - An API key. It is the SMTP password and the key your Edge Functions use. Create one on the API keys page.
The free plan needs no credit card.
Set up custom SMTP in Supabase
Custom SMTP keeps Supabase in charge of the emails: it renders its templates and hands each message to Nuntly's SMTP relay.
In the Supabase dashboard, open Authentication, then Emails, then the SMTP Settings tab, and turn on Enable custom SMTP. Fill in the fields:
| Field | Value |
|---|---|
| Sender email address | auth@mail.example.com (on your verified domain) |
| Sender name | Your app name |
| Host | smtp.nuntly.com |
| Port number | 587 |
| Username | nuntly |
| Password | Your Nuntly API key (starts with ntly_) |
Then click Save changes. Port 587 uses STARTTLS, the only mode Nuntly's relay accepts. The SMTP guide has the full relay settings.
You can set the same values with the Management API (custom SMTP docs), which helps when you manage several projects:
curl -X PATCH "https://api.supabase.com/v1/projects/$PROJECT_REF/config/auth" \-H "Authorization: Bearer $SUPABASE_ACCESS_TOKEN" \-H "Content-Type: application/json" \-d '{"smtp_admin_email": "auth@mail.example.com","smtp_sender_name": "Acme","smtp_host": "smtp.nuntly.com","smtp_port": "587","smtp_user": "nuntly","smtp_pass": "'"$NUNTLY_API_KEY"'","rate_limit_email_sent": 30}'
The last field matters: in our test on November 14, 2026, saving SMTP through the Management API left the project at 2 emails per hour, while the dashboard raises it on save.
Raise the 30 emails per hour limit
Saving custom SMTP in the dashboard lifts the team-only restriction, and Supabase sets the project limit to 30 emails per hour (custom SMTP docs). Raise it on Authentication, Rate Limits before you launch: 30 per hour is about one sign-up every two minutes.
Keep link tracking off
Supabase recommends turning off link tracking on your SMTP provider, because rewritten links can break its confirmation links (production checklist). Open and click tracking are off by default on a Nuntly domain. Leave click tracking off on the domain that sends your auth emails.
Send a test email
Sign up with an address outside your Supabase team, or send a password reset from Authentication, Users. The email shows up in the Nuntly dashboard with its delivery status, and its link points at your project's /auth/v1/verify endpoint, unchanged.
Send auth emails with the Send Email Hook
The Send Email Hook replaces Supabase's sending: for each auth email, Supabase POSTs a signed JSON payload to your endpoint and your code sends the email. Use it when you want your own templates, one email per language, or tags on every message.
Send Email Hook: an HTTP endpoint that Supabase Auth calls instead of its mailer, with the user and an email_action_type that names the email to send.
The hook is available on the Free and Pro plans (Auth Hooks docs).
What Supabase sends
Each call carries a user object and an email_data object (payload schema):
{"user": { "email": "jane@example.com", "new_email": "" },"email_data": {"token": "305805","token_hash": "7d5b7b1964cf5d388340a7f04f1dbb5eeb6c7b52ef8270e1737a58d0","redirect_to": "http://localhost:3000/","email_action_type": "signup","site_url": "https://project-ref.supabase.co/auth/v1","token_new": "","token_hash_new": ""}}
token is the one-time code. token_hash goes into the confirmation link, which points at your project's /auth/v1/verify endpoint.
Map each email_action_type to an email
email_action_type | Email to send | What it contains |
|---|---|---|
signup | Confirm the address | Link |
invite | Accept an invitation | Link |
magiclink | Sign in | Link and code |
recovery | Reset the password | Link |
email_change | Confirm the new address | Link and code, one or two emails |
reauthentication | Confirm a sensitive action | Code |
*_notification (7 types) | Security notice, no action | Text only |
The seven notification types are password_changed_notification, email_changed_notification, phone_changed_notification, identity_linked_notification, identity_unlinked_notification, mfa_factor_enrolled_notification and mfa_factor_unenrolled_notification. Supabase only sends the ones enabled for the project (email templates docs).
The schema also lists email. Supabase Auth uses it as a verification type and, in the Auth source read on November 14, 2026, never passes it to the hook. The function below rejects any type it doesn't know, so a new one shows up as an error instead of a missing email.
email_change sends one or two emails. With Secure email change on (the default), the user confirms from both addresses. The field names are crossed for backward compatibility, as the hook docs warn:
- current address (
user.email):tokenwithtoken_hash_new - new address (
user.new_email):token_newwithtoken_hash
With it off, Supabase sends a single pair for the new address.
Write the Edge Function
Create the function with the Supabase CLI:
supabase functions new send-email
Replace supabase/functions/send-email/index.ts with:
import { Webhook } from 'npm:standardwebhooks@1.1.1';import { createSafeNuntly } from 'npm:@nuntly/sdk@2.0.0';const nuntly = createSafeNuntly({ apiKey: Deno.env.get('NUNTLY_API_KEY') });const webhook = new Webhook(Deno.env.get('SEND_EMAIL_HOOK_SECRET')!.replace('v1,whsec_', ''));const FROM = Deno.env.get('EMAIL_FROM')!; // e.g. 'Acme <auth@mail.example.com>'const VERIFY_URL = `${Deno.env.get('SUPABASE_URL')}/auth/v1/verify`;interface HookEvent {user: { email: string; new_email?: string };email_data: {token: string;token_hash: string;token_new: string;token_hash_new: string;redirect_to: string;email_action_type: string;};}interface Message {to: string;subject: string;text: string;html: string;}// One email: a sentence, then a link, a code, or both.function message(to: string,subject: string,body: string,link?: string,code?: string,): Message {const lines = [body, link, code && `Code: ${code}`].filter(Boolean) as string[];const html = [`<p>${body}</p>`,link ? `<p><a href="${link}">${subject}</a></p>` : '',code ? `<p>Code: <strong>${code}</strong></p>` : '',].join('');return { to, subject, text: lines.join('\n\n'), html };}function verifyLink(data: HookEvent['email_data'], tokenHash: string): string {const params = new URLSearchParams({token: tokenHash,type: data.email_action_type,redirect_to: data.redirect_to,});return `${VERIFY_URL}?${params}`;}const NOTIFICATIONS: Record<string, string> = {password_changed_notification: 'Your password was changed',email_changed_notification: 'Your email address was changed',phone_changed_notification: 'Your phone number was changed',identity_linked_notification: 'A sign-in method was linked to your account',identity_unlinked_notification: 'A sign-in method was removed from your account',mfa_factor_enrolled_notification: 'A second factor was added to your account',mfa_factor_unenrolled_notification: 'A second factor was removed from your account',};function buildMessages({ user, email_data: data }: HookEvent): Message[] {const link = verifyLink(data, data.token_hash);switch (data.email_action_type) {case 'signup':return [message(user.email, 'Confirm your email', 'Confirm your address.', link)];case 'invite':return [message(user.email, 'Accept your invitation', 'You were invited.', link)];case 'magiclink':return [message(user.email, 'Your sign-in link', 'Sign in.', link, data.token)];case 'recovery':return [message(user.email, 'Reset your password', 'Choose a new one.', link)];case 'reauthentication':return [message(user.email, 'Your code', 'Enter this code.', undefined, data.token)];case 'email_change': {const newEmail = user.new_email!;// Secure email change on: token_hash_new goes with the current address.if (data.token_hash_new) {const currentLink = verifyLink(data, data.token_hash_new);return [message(user.email, 'Confirm your email change', 'Confirm.', currentLink, data.token),message(newEmail, 'Confirm your new email', 'Confirm.', link, data.token_new),];}return [message(newEmail, 'Confirm your new email', 'Confirm.', link, data.token)];}default: {const subject = NOTIFICATIONS[data.email_action_type];if (!subject) throw new Error(`Unknown email_action_type: ${data.email_action_type}`);return [message(user.email, subject, `${subject}. If this wasn't you, contact support.`)];}}}Deno.serve(async (req) => {let event: HookEvent;try {event = webhook.verify(await req.text(), Object.fromEntries(req.headers)) as HookEvent;} catch {const error = { http_code: 401, message: 'Invalid signature' };return Response.json({ error }, { status: 401 });}let messages: Message[];try {messages = buildMessages(event);} catch (err) {return Response.json({ error: { http_code: 500, message: (err as Error).message } });}for (const email of messages) {const { error } = await nuntly.emails.send({from: FROM,...email,tags: [{ name: 'supabase', value: event.email_data.email_action_type }],});if (error) {return Response.json({ error: { http_code: 500, message: 'Email could not be sent' } });}}return Response.json({});});
The function does three things:
- Verifies the signature. Supabase signs each call with the Standard Webhooks scheme:
webhook-id,webhook-timestampandwebhook-signatureheaders.webhook.verifythrows on a bad signature or an old timestamp, and the function answers 401 without sending anything. - Builds one or two emails from
email_action_type. The subjects and sentences are placeholders: put your own copy or rendered templates there. - Sends through Nuntly and answers
{}. Each email carries asupabasetag with its type, shown on the email's page in the Nuntly dashboard and in webhook events.
Three details come from how Supabase Auth calls the hook (hook client source, read on November 14, 2026):
- A 200 must carry
Content-Type: application/json.Response.jsonsets it. A barenew Response(null)makes Auth reject the call even though your email went out. - Errors go in the body. Auth returns your
messageto the client only from a 200 response with anerrorobject. A 4xx or 5xx status becomes a generic error. - The call times out after 5 seconds. Keep the function to the send itself: no slow API calls before it.
Deploy and enable the hook
-
In the Supabase dashboard, open Authentication, then Hooks, add a Send Email hook of type HTTPS, and generate a secret. It looks like
v1,whsec_.... -
Store the secrets for the function.
SUPABASE_URLis already set on hosted projects.Shellsupabase secrets set \NUNTLY_API_KEY=ntly_... \SEND_EMAIL_HOOK_SECRET='v1,whsec_...' \EMAIL_FROM='Acme <auth@mail.example.com>' -
Deploy without JWT verification. Supabase Auth authenticates with the signature, not with a user token:
Shellsupabase functions deploy send-email --no-verify-jwt -
Back in Hooks, set the URL to
https://<project-ref>.supabase.co/functions/v1/send-emailand enable the hook.
Sign up a test user: the confirmation email arrives with your own subject and the supabase: signup tag.
We ran this function on a hosted Supabase project on November 14, 2026, for sign-up, magic link and password reset emails. The email_change and notification branches were run locally against signed payloads.
The hook keeps Supabase's email rate limit: raise it on Authentication, Rate Limits as you would with SMTP (rate limits).
Send app emails from Edge Functions
Order confirmations, workspace invitations and alerts come from your own code, not from Supabase Auth. An Edge Function sends them with the same SDK and API key.
This function sends an order confirmation. Save it as supabase/functions/order-confirmed/index.ts. It reads the same NUNTLY_API_KEY and EMAIL_FROM secrets as the hook function. It accepts calls carrying your project's secret key, which is how a database webhook calls it (securing Edge Functions):
import { withSupabase } from 'npm:@supabase/server@1';import { createSafeNuntly } from 'npm:@nuntly/sdk@2.0.0';const nuntly = createSafeNuntly({ apiKey: Deno.env.get('NUNTLY_API_KEY') });export default {fetch: withSupabase({ auth: 'secret' }, async (req) => {// Database webhook payload: { type, table, schema, record, old_record }const { record } = await req.json();const { error } = await nuntly.emails.send({from: Deno.env.get('EMAIL_FROM')!,to: record.customer_email,subject: `Order ${record.id} confirmed`,text: `We received your order ${record.id}.`,html: `<p>We received your order ${record.id}.</p>`,tags: [{ name: 'type', value: 'order-confirmed' }],},{ idempotencyKey: `order-confirmed-${record.id}` },);if (error) {return Response.json({ error: 'Email could not be sent' }, { status: 502 });}return Response.json({ ok: true });}),};
The idempotency key ties the email to the order: if the function runs twice for the same row, Nuntly sends one email.
We ran this function on the same hosted project on November 14, 2026: the email arrived, and a second call for the same order sent nothing.
Deploy it without the platform JWT check, since the caller presents a secret key instead of a user token. verify_jwt = false under [functions.order-confirmed] in supabase/config.toml does the same:
supabase functions deploy order-confirmed --no-verify-jwt
Trigger it when a row is inserted
A Database Webhook calls the function after each INSERT, UPDATE or DELETE on a table. It is a trigger that uses the pg_net extension, so the HTTP call doesn't block your insert (Database Webhooks docs).
- In the Supabase dashboard, create a Database Webhook on
public.ordersforINSERT. - In Type of webhook, choose Supabase Edge Functions and select
order-confirmed. - Under HTTP Headers, choose Add secret key.
Supabase stores that key in the trigger definition, so it appears in database dumps. Its docs show how to read it from Vault in a migration instead.
Self-hosted Supabase: SMTP environment variables
A self-hosted instance has no SMTP form: Auth reads its settings from the .env file of the Docker setup (self-hosting with Docker). Supabase's example uses port 465, which Nuntly doesn't accept. Use 587:
SMTP_ADMIN_EMAIL=auth@mail.example.comSMTP_HOST=smtp.nuntly.comSMTP_PORT=587SMTP_USER=nuntlySMTP_PASS=ntly_your_api_keySMTP_SENDER_NAME=Acme
Restart the stack to apply them. These values follow Supabase's self-hosting docs; this guide tested custom SMTP and the hook on hosted Supabase, not on a self-hosted instance.
Troubleshooting
| Error or symptom | Cause | Fix |
|---|---|---|
Email address not authorized | Default sender, recipient outside the team | Enable custom SMTP or the hook |
email rate limit exceeded | Project hourly email limit reached | Raise it under Rate Limits |
| Confirmation link fails | Link rewritten or already used | Keep click tracking off on that domain |
Hook: Invalid Content-Type | 200 sent without a JSON body | Answer with Response.json({}) |
Hook: Failed to reach hook | No answer within 5 seconds | Check function logs, slim the function |
The hook error texts come from the hook client source and email rate limit exceeded from mail.go, both read on November 14, 2026.
A confirmation link can also fail when a mail provider or scanner prefetches it before the user does, because the link is consumed on first use. Supabase's email templates docs suggest linking to a page on your site that asks the user to click before calling the verify URL.
Before you launch
Whichever method you pick, check these five points before real users sign up:
- The sender address is on a domain verified in Nuntly.
- Custom SMTP or the Send Email Hook is on, so emails reach addresses outside your team.
- The email rate limit under Authentication, Rate Limits fits the sign-ups you expect.
- Click tracking stays off on the domain that sends auth emails.
- A test sign-up from an address outside your team arrives, and its link confirms the account.
Custom SMTP is the shortest path: no code, and Supabase keeps rendering its templates. Move auth emails to the Send Email Hook when you need your own templates or languages, and send app emails from Edge Functions with the same API key. The SMTP guide covers the relay settings, and Send your first email covers the API. The Supabase page in the docs keeps every setting from this guide on one page.
Ship emails, not infrastructure
Free plan available. No credit card required.
Start for freeFrequently asked questions
Common questions about this topic.
Supabase's Google SMTP article describes a working setup with constraints: the sender and SMTP username must be the Google Workspace admin address, the password must be an app password (which needs 2FA on that account), and smtp-relay.gmail.com only works on port 465.
Use a Database Webhook that calls an Edge Function, as in Trigger it when a row is inserted. The webhook fires after the insert, update or delete, and the function sends the email with the row it receives.
No. When the hook is enabled, Supabase sends every auth email through it and doesn't use SMTP (Send Email Hook docs). Keeping SMTP configured gives you a fallback: disable the hook and Supabase goes back to SMTP (Auth source, read on November 14, 2026).