Skip to content
DocumentationAPI reference Build something worth sending.

Guides

Supabase custom SMTP not working

Why Supabase auth emails fail with custom SMTP: rate limits, ports, sender domain and spam. Then send them through an email API with a Send Email hook.

Supabase Auth sends signup confirmations, magic links and password resets. Its built-in mail service is for testing: it only sends to addresses on your organization's team, and it allows 2 emails an hour for the whole project. An address outside the team fails with Email address not authorized. For real users you need custom SMTP or a Send Email hook. This guide covers why custom SMTP fails, then how to send the same emails through an HTTP email API.

Why custom SMTP is not working

Custom SMTP is not switched on

If you still see Email address not authorized, Supabase is using the built-in service. Open Authentication, then the SMTP settings, turn on custom SMTP, fill in the host, port, username, password and sender address, and save. A form that was filled in but not enabled changes nothing.

The email rate limit

With custom SMTP the project limit starts at 30 emails an hour. Above it, signups and resets return a 429 error with an email rate limit message, even though your SMTP provider would accept more. Raise it under Authentication, Rate Limits. There is also a 60-second window per user for signup, magic link and recovery requests, so pressing "resend" twice in a row also fails.

The port and TLS do not match

Use port 587 for STARTTLS or 465 for TLS from the first byte, whichever your provider documents. Port 25 is blocked by many cloud networks. A wrong pairing usually shows as a timeout or a handshake error in the Auth logs rather than a clear message.

The username or password is not what you expect

Many providers do not use your account login for SMTP. Some use a fixed username with an API key as the password, others give you SMTP credentials that are separate from the API key. Copy both from the provider's SMTP page, and check the key is allowed to send.

The sender address is not on a verified domain

The sender email in Supabase must be on a domain you verified with the provider. A Gmail address or an unverified domain is refused or silently dropped. Use something like no-reply@auth.your-domain.com, and keep auth mail on its own subdomain or address, apart from marketing mail.

Emails arrive in spam

Publish SPF, DKIM and DMARC for the sending domain and check them with the SPF checker, DKIM checker and DMARC checker. Keep the templates short and plain: one link, no promotion, no images you do not need. SPF, DKIM and DMARC explained covers what each record checks.

The link opens localhost

The links in auth emails use the Site URL and the allowed redirect URLs under Authentication, URL Configuration. If they still point at http://localhost:3000, users get a broken link even though the email arrived.

Send auth emails through an API instead

A Send Email hook replaces SMTP. Supabase calls an HTTPS endpoint you own with the user and the token, and your code sends the email. When the hook is on, Supabase does not use SMTP at all. This is how you use a provider that has an HTTP API but no SMTP relay, and SendPanda is one: it sends through its API and SDK only. You also choose the subject and body in code rather than in the Supabase template editor.

1. Write the Edge Function

Supabase signs each hook request with the Standard Webhooks scheme. Verify it with the standardwebhooks library before you trust the payload. The webhook-id header is the same on a retry, so it makes a good idempotency key: a retried hook does not send the email twice.

// supabase/functions/send-email/index.ts
import { Webhook } from "https://esm.sh/standardwebhooks@1.0.0";

const hookSecret = Deno.env
  .get("SEND_EMAIL_HOOK_SECRET")!
  .replace("v1,whsec_", "");
const apiKey = Deno.env.get("SENDPANDA_API_KEY")!;
const supabaseUrl = Deno.env.get("SUPABASE_URL")!;

const subjects: Record<string, string> = {
  signup: "Confirm your email",
  magiclink: "Your sign-in link",
  recovery: "Reset your password",
  invite: "You have been invited",
  email_change: "Confirm your new email",
};

type HookEvent = {
  user: { email: string };
  email_data: {
    token: string;
    token_hash: string;
    redirect_to: string;
    email_action_type: string;
  };
};

Deno.serve(async (req) => {
  const payload = await req.text();
  const headers = Object.fromEntries(req.headers);
  let event: HookEvent;
  try {
    event = new Webhook(hookSecret).verify(payload, headers) as HookEvent;
  } catch {
    return Response.json(
      { error: { http_code: 401, message: "Invalid signature" } },
      { status: 401 },
    );
  }

  const { user, email_data } = event;
  const link = new URL(`${supabaseUrl}/auth/v1/verify`);
  link.searchParams.set("token", email_data.token_hash);
  link.searchParams.set("type", email_data.email_action_type);
  link.searchParams.set("redirect_to", email_data.redirect_to);

  const res = await fetch("https://api.sendpanda.email/v1/emails", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${apiKey}`,
      "Content-Type": "application/json",
      "Idempotency-Key": `supabase-${headers["webhook-id"]}`,
    },
    body: JSON.stringify({
      from: "Your app <no-reply@auth.your-domain.com>",
      to: [user.email],
      subject: subjects[email_data.email_action_type] ?? "Your account",
      text: `Open this link to continue:\n${link}\n\nOr enter this code: ${email_data.token}`,
    }),
  });

  if (!res.ok) {
    return Response.json(
      { error: { http_code: 500, message: "The email was not sent" } },
      { status: 500 },
    );
  }
  return Response.json({});
});

Add an html field next to text when you want a designed email, or send a published template with template_id and variables. The from address must be on a domain you verified in SendPanda: see domain setup.

2. Set the secrets and deploy

supabase secrets set SENDPANDA_API_KEY=sp_live_your_key
supabase secrets set SEND_EMAIL_HOOK_SECRET="v1,whsec_your_secret"
supabase functions deploy send-email --no-verify-jwt

The hook request carries a signature, not a Supabase user token, so deploy without JWT verification and rely on the signature check in the code. SUPABASE_URL is set for every Edge Function, so you do not add it yourself.

3. Turn the hook on

In the dashboard, open Authentication, Hooks, add a Send Email hook, choose HTTPS and enter https://your-project-ref.supabase.co/functions/v1/send-email. Generate the secret there and copy it into SEND_EMAIL_HOOK_SECRET before you save. Then sign up with an address outside your team to check the whole path.

Two cases the example leaves out

  • Secure email change. When it is on, an email_change event needs two emails, one to the old address and one to the new. Supabase sends a second token and hash for this, and the field names are paired the opposite way from what you might guess: check the Supabase hook reference before you build it.
  • Security notifications. If you turn on notices such as a changed password, the hook also receives types like password_changed_notification. These have no link to confirm, so send a plain notice for them instead of a verify link.

The hook raises the Supabase email limit too, but your sending provider's own quota still applies. SendPanda includes 3,000 emails a month free, which covers the auth mail of most new apps. See password-reset and magic-link emails for the same emails sent from your own server.

Next steps

↑↓ to navigate↵ to openesc to close