TutorialSupabaseSMTP

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.

Olivier Bazoud
November 14, 2026
16 min read

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

MethodWho writes the emailUse it for
Custom SMTPSupabase templatesAuth emails, no code to deploy
Send Email HookYour Edge FunctionAuth emails with your own templates, languages or logic
Edge FunctionYour Edge FunctionApp emails: receipts, notifications
Self-hosted SMTPSupabase templatesAuth 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:

  1. 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.
  2. 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:

FieldValue
Sender email addressauth@mail.example.com (on your verified domain)
Sender nameYour app name
Hostsmtp.nuntly.com
Port number587
Usernamenuntly
PasswordYour 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:

Shell
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.

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):

JSON
{
"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_typeEmail to sendWhat it contains
signupConfirm the addressLink
inviteAccept an invitationLink
magiclinkSign inLink and code
recoveryReset the passwordLink
email_changeConfirm the new addressLink and code, one or two emails
reauthenticationConfirm a sensitive actionCode
*_notification (7 types)Security notice, no actionText 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): token with token_hash_new
  • new address (user.new_email): token_new with token_hash

With it off, Supabase sends a single pair for the new address.

Write the Edge Function

Create the function with the Supabase CLI:

Shell
supabase functions new send-email

Replace supabase/functions/send-email/index.ts with:

TypeScript
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:

  1. Verifies the signature. Supabase signs each call with the Standard Webhooks scheme: webhook-id, webhook-timestamp and webhook-signature headers. webhook.verify throws on a bad signature or an old timestamp, and the function answers 401 without sending anything.
  2. Builds one or two emails from email_action_type. The subjects and sentences are placeholders: put your own copy or rendered templates there.
  3. Sends through Nuntly and answers {}. Each email carries a supabase tag 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.json sets it. A bare new Response(null) makes Auth reject the call even though your email went out.
  • Errors go in the body. Auth returns your message to the client only from a 200 response with an error object. 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

  1. 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_....

  2. Store the secrets for the function. SUPABASE_URL is already set on hosted projects.

    Shell
    supabase secrets set \
    NUNTLY_API_KEY=ntly_... \
    SEND_EMAIL_HOOK_SECRET='v1,whsec_...' \
    EMAIL_FROM='Acme <auth@mail.example.com>'
  3. Deploy without JWT verification. Supabase Auth authenticates with the signature, not with a user token:

    Shell
    supabase functions deploy send-email --no-verify-jwt
  4. Back in Hooks, set the URL to https://<project-ref>.supabase.co/functions/v1/send-email and 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):

TypeScript
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:

Shell
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).

  1. In the Supabase dashboard, create a Database Webhook on public.orders for INSERT.
  2. In Type of webhook, choose Supabase Edge Functions and select order-confirmed.
  3. 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:

Shell
SMTP_ADMIN_EMAIL=auth@mail.example.com
SMTP_HOST=smtp.nuntly.com
SMTP_PORT=587
SMTP_USER=nuntly
SMTP_PASS=ntly_your_api_key
SMTP_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 symptomCauseFix
Email address not authorizedDefault sender, recipient outside the teamEnable custom SMTP or the hook
email rate limit exceededProject hourly email limit reachedRaise it under Rate Limits
Confirmation link failsLink rewritten or already usedKeep click tracking off on that domain
Hook: Invalid Content-Type200 sent without a JSON bodyAnswer with Response.json({})
Hook: Failed to reach hookNo answer within 5 secondsCheck 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:

  1. The sender address is on a domain verified in Nuntly.
  2. Custom SMTP or the Send Email Hook is on, so emails reach addresses outside your team.
  3. The email rate limit under Authentication, Rate Limits fits the sign-ups you expect.
  4. Click tracking stays off on the domain that sends auth emails.
  5. 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.

Ready to get started?

Ship emails, not infrastructure

Free plan available. No credit card required.

Start for free
FAQ

Frequently 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).