Supabase SMTP with Volanea: Send Auth Emails Reliably

Supabase SMTP lets you route confirmation emails, password resets, magic links, and invitations through an email provider you control. This guide shows how to connect Volanea to Supabase SMTP, then send a real transactional invite email from a secure Node.js server.

This is an SMTP integration, not a Volanea-specific application SDK integration. Supabase Auth creates the email and sends it through the custom SMTP credentials you configure; Volanea accepts the SMTP message and handles delivery. Your application code therefore uses the Supabase SDK, while the Volanea SMTP credentials live in Supabase’s SMTP configuration.

What you are building

By the end of this guide, you will have:

1. A Volanea sending domain ready for transactional email.
2. Volanea SMTP credentials configured in your Supabase project.
3. A server-side Node.js script using @supabase/supabase-js.
4. A transactional Supabase Auth invitation delivered through your configured Volanea SMTP relay.
5. A troubleshooting process for the errors most likely to occur in this stack.

The sample sends an invitation email using supabase.auth.admin.inviteUserByEmail(). That is a useful end-to-end test because it exercises the full path:

Node.js server → Supabase Auth Admin API → Supabase custom SMTP → Volanea → recipient mailbox

Use this pattern for administration workflows, team invitations, or internal systems that create users on behalf of an operator. Do not place the secret Supabase key in browser code, a mobile app, or any client-exposed environment variable.

How Supabase SMTP and Volanea fit together

Supabase Auth sends several types of transactional messages. Depending on your enabled auth flows, these may include:

• Email-confirmation messages after sign-up.
• Password recovery emails.
• Magic-link and one-time-password emails.
• User invitation emails.
• Email-change confirmation messages.

Supabase includes a default mail service for testing, but its sending restrictions make it unsuitable for a real production authentication flow. Configuring custom SMTP tells Supabase to deliver Auth email through the provider credentials you supply instead.

With Volanea configured as that provider, there are two separate authentication layers to keep straight:

This distinction matters. Your Node.js script does not need direct access to Volanea SMTP credentials to send a Supabase Auth invite. The script authenticates to Supabase. Supabase then authenticates to Volanea using the SMTP configuration stored in your project.

Keeping these credentials separate reduces accidental exposure and makes credential rotation simpler. If you change Volanea SMTP credentials, update the custom SMTP configuration in Supabase; application code that only calls Supabase Auth does not need to change.

Before you start

Prepare the following items before configuring Supabase SMTP.

A verified sending domain in Volanea

Use a From address on a domain that is configured and verified for sending in Volanea. For example, if your product sends from support@example.com, make sure example.com is an authenticated sending domain in your Volanea account.

Domain authentication is not merely a cosmetic setup task. It allows receiving mailbox providers to evaluate whether your sending infrastructure is authorized to send mail for the domain in the From address. A mismatch between your configured sender and your verified sender domain can cause rejection, spam placement, or provider-side policy failures.

Do not use a personal mailbox address as a shortcut for a production authentication flow. Use a sender such as:

no-reply@example.com
support@example.com
accounts@example.com

Choose an address people recognize, and ensure it belongs to the domain you configured for Volanea sending.

Volanea SMTP connection details

Get the current SMTP settings issued for your Volanea account. Supabase needs these values:

• SMTP host
• SMTP port
• SMTP username
• SMTP password
• Sender email
• Sender name

Do not guess the hostname, select a port from a generic blog post, or reuse credentials from another provider. Use the exact connection values shown in your Volanea account setup material. SMTP credentials are provider-specific and may be scoped or rotated separately from REST API keys.

A Supabase project and Auth email flow

You need a Supabase project with Auth enabled. The project should also have an application URL and redirect URLs configured for the application environment where users will complete invitation, recovery, or confirmation flows.

For the invite example in this guide, use a redirect URL that you have explicitly allowed in your Supabase Auth URL configuration. A typical local development URL is:

http://localhost:3000/auth/callback

A typical production URL is:

https://app.example.com/auth/callback

A trusted server runtime

The code sample runs in Node.js and uses a Supabase secret key. Run it only in a trusted environment, such as:

• A Node.js backend.
• A protected server route.
• A background worker.
• A private administrative tool.
• A CI job used for controlled provisioning.

Do not run it in a React browser bundle, static client-side JavaScript file, public GitHub repository, or browser extension. Admin methods can create and invite users, and the secret key must remain confidential.

Configure Volanea in Supabase SMTP settings

Supabase accepts any provider that supports SMTP. Once you have Volanea’s account-issued SMTP values, configure them in the Supabase dashboard.

1. Open the Supabase project that owns your Auth users.
2. Select Authentication in the project navigation.
3. Open Email under the Notifications section.
4. Open SMTP Settings.
5. Enable custom SMTP.
6. Enter the sender email and sender name that should appear on your Auth emails.
7. Copy the Volanea SMTP host, port, username, and password into the corresponding SMTP fields.
8. Save the configuration.

The sender email should be an address associated with the domain you have authenticated for Volanea. If you configure accounts@example.com in Supabase but only verify example.net in Volanea, delivery may fail or the sender may not align with your domain policy.

Choose the correct sender identity

The sender name and sender email are part of your product’s authentication experience. They should make it clear why the recipient received the message.

Good examples:

Sender name: Acme Accounts
Sender email: accounts@example.com

Sender name: Acme Support
Sender email: support@example.com

Avoid vague or misleading identities such as a personal employee mailbox, a sender name unrelated to the product, or an address from a domain you do not control.

Keep Supabase Auth templates separate from SMTP delivery

SMTP configuration controls how Supabase delivers messages. Supabase Auth email templates control what the recipient sees.

That separation is useful:

• Change Volanea credentials when your SMTP credentials rotate.
• Change a Supabase Auth template when you update product copy or branding.
• Change your application redirect URL when you deploy to another environment.

Do not expect SMTP settings alone to change the content, logo, links, or wording of an invite email. Update the relevant Supabase Auth template when you need to change the message itself.

Install the Supabase SDK

The working example uses the official Supabase JavaScript client. It sends one transactional invite email through Supabase Auth, which then uses your configured Volanea SMTP relay.

Use Node.js 20.6 or later so that the command can load the .env file with Node’s built-in --env-file option.

npm install @supabase/supabase-js

Create a new project directory if you need one:

mkdir supabase-volanea-smtp
cd supabase-volanea-smtp
npm init -y
npm install @supabase/supabase-js

The install command adds the dependency that initializes the Supabase client and calls the Auth Admin API. There is no Volanea SDK in this example because Supabase is the component opening the SMTP connection after you configure custom SMTP in the dashboard.

Add server-only environment variables

Create a file named .env in the project directory:

SUPABASE_URL=https://YOUR_PROJECT_REF.supabase.co
SUPABASE_SECRET_KEY=your-supabase-secret-key
SUPABASE_INVITE_REDIRECT_URL=http://localhost:3000/auth/callback

Replace each value with the value for your Supabase project.

SUPABASE_SECRET_KEY is intentionally named to make its sensitivity obvious. It must be a server-side secret key that can call Supabase Auth admin methods. Do not use a browser-safe publishable key for this script, and do not expose the secret key to untrusted clients.

Add .env to .gitignore before continuing:

.env

If your deployment platform provides environment-variable management, configure these values there rather than uploading a .env file. Local .env files are for development convenience, not a secret-management strategy for shared or production environments.

Where Volanea credentials belong

Your Volanea SMTP values should be entered in Supabase custom SMTP settings, not copied into this Node script. This is intentional.

The process is:

1. Your application authenticates to Supabase with SUPABASE_SECRET_KEY.
2. The application asks Supabase to create and send an invitation.
3. Supabase renders the configured invitation email.
4. Supabase connects to Volanea using the SMTP credentials saved in the project’s SMTP settings.
5. Volanea accepts the message for delivery.

If you also send non-Auth product emails directly from your backend, you may use Volanea’s REST API or SMTP credentials in a separate server-side integration. Keep that implementation distinct from the Supabase Auth SMTP configuration so you can identify which system generated each category of mail.

Complete working code sample

Create a file named send-invite.mjs:

import { createClient } from '@supabase/supabase-js';

const {
  SUPABASE_URL,
  SUPABASE_SECRET_KEY,
  SUPABASE_INVITE_REDIRECT_URL,
} = process.env;

const recipientEmail = process.argv[2];

if (!SUPABASE_URL) {
  throw new Error('Missing SUPABASE_URL. Add it to your .env file.');
}

if (!SUPABASE_SECRET_KEY) {
  throw new Error('Missing SUPABASE_SECRET_KEY. Add it to your .env file.');
}

if (!SUPABASE_INVITE_REDIRECT_URL) {
  throw new Error(
    'Missing SUPABASE_INVITE_REDIRECT_URL. Add an allowed Auth redirect URL to .env.'
  );
}

if (!recipientEmail) {
  throw new Error(
    'Usage: node --env-file=.env send-invite.mjs recipient@example.com'
  );
}

const supabase = createClient(SUPABASE_URL, SUPABASE_SECRET_KEY, {
  auth: {
    autoRefreshToken: false,
    persistSession: false,
    detectSessionInUrl: false,
  },
});

const { data, error } = await supabase.auth.admin.inviteUserByEmail(
  recipientEmail,
  {
    redirectTo: SUPABASE_INVITE_REDIRECT_URL,
  }
);

if (error) {
  console.error('Supabase invite failed:', error.message);
  process.exitCode = 1;
} else {
  console.log('Invitation email accepted by Supabase Auth.');
  console.log(`Recipient: ${recipientEmail}`);
  console.log(`User ID: ${data.user?.id ?? 'not returned'}`);
  console.log(
    'Supabase will deliver the invitation through your configured Volanea SMTP settings.'
  );
}

Run the script with a new test recipient address:

node --env-file=.env send-invite.mjs recipient@example.com

If Supabase accepts the request, the script prints a confirmation. That confirmation means the Auth Admin API accepted the invitation request. It does not guarantee that the recipient has already opened the message or that the message has reached the inbox; SMTP providers and mailbox providers process delivery asynchronously.

Check the recipient mailbox, including spam and quarantine folders, then review the relevant delivery activity in your sending provider if the message is not visible.

Why this sample is copy-pasteable

The sample contains the pieces commonly omitted in short examples:

• The exact package installation command.
• Environment-variable validation before an API call.
• A server-side client initialization using a secret API key.
• Server-friendly Auth settings that disable browser session behavior.
• await on the asynchronous invitation request.
• Error handling that returns a nonzero exit code on failure.
• A command-line recipient address, so you do not need to edit source code to test a different inbox.

It also avoids embedding any secret directly in the code. You can copy the file, add valid environment values, configure Volanea in Supabase SMTP settings, and run the command.

Test the full delivery path

A successful script run validates only part of the integration. Test every stage of the delivery path before relying on it for production sign-ups or account recovery.

Use a fresh recipient for invitation testing

An invitation flow creates an invitation for a user. Reusing the same address after a previous invite or after that user has accepted an invitation may produce a different result than a first-time test.

For clean testing, use an address that has not yet been invited to the project. Record the time you ran the command and the recipient address. Those details help when comparing application logs, Supabase Auth logs, and delivery events in your email provider.

Verify the redirect experience

Open the received invitation email and follow the link. Confirm that it sends the user to the expected application route after the authentication action completes.

If the link leads to an unexpected URL, fails validation, or redirects to localhost in production, review both:

• SUPABASE_INVITE_REDIRECT_URL in your server environment.
• The allowed redirect URLs configured in Supabase Auth.

Your redirect URL should be environment-specific. Do not use a development URL in production, and do not broadly allow arbitrary redirect domains just to make a test pass.

Check sender alignment

Inspect the received email and verify that the visible From address matches the sender address configured in Supabase. The address should use the Volanea-authenticated domain you intended.

If the sender is not what you expected, revisit the custom SMTP configuration and your Supabase Auth email settings. Do not try to alter sender identity by editing application code that merely calls inviteUserByEmail(); Supabase owns the generated invitation message and uses its configured sender information.

Separate acceptance from inbox placement

There are multiple success states in an email workflow:

1. Your Node process successfully calls Supabase.
2. Supabase accepts the Auth action and builds the message.
3. Supabase authenticates to the custom SMTP relay.
4. Volanea accepts the SMTP transaction.
5. The receiving mailbox provider accepts, filters, defers, or rejects the message.
6. The recipient sees the message in the inbox, spam folder, or a quarantine system.

A failure at any stage needs a different fix. Treating every missing email as an SDK failure leads to wasted debugging time. Start with the latest confirmed stage, then inspect the system responsible for the next stage.

Common errors

This section covers the errors and configuration mistakes that occur most often when sending Supabase Auth messages through custom SMTP.

Authentication fails or Supabase reports an unauthorized admin request

Symptoms: The script returns an authorization error, an invalid API key error, or a permission error before any email is generated.

Likely cause: You used a publishable or anonymous key instead of a Supabase secret key, the key has been rotated, or the environment variable is missing or contains whitespace.

Fix:

• Confirm that SUPABASE_SECRET_KEY contains a valid server-side secret key for the same project as SUPABASE_URL.
• Keep the key in a server-only secret store or local .env file excluded from Git.
• Restart the process after changing environment variables.
• Do not expose this key in client-side code.

The auth.admin namespace requires a secret key because it can create, update, invite, and manage users. A public key is intentionally insufficient for this operation.

Volanea SMTP authentication fails after Supabase accepts the Auth request

Symptoms: Supabase Auth cannot deliver its email, SMTP authentication fails, or a test message never reaches the provider because the SMTP relay rejects login.

Likely cause: One or more Volanea SMTP values in Supabase are incorrect, stale, copied with whitespace, or intended for another account or environment.

Fix:

• Recopy the SMTP host, port, username, and password from the current Volanea account-issued settings.
• Do not substitute a generic hostname or port.
• Confirm that the SMTP credential is active and authorized for sending.
• Save the SMTP configuration again after updating the values.
• Rotate the SMTP password if you suspect it was exposed, then update Supabase immediately.

Do not confuse Volanea REST API credentials with SMTP credentials unless the Volanea setup instructions explicitly say the same value is valid for both. The safe rule is to use the credential type and connection fields issued for the SMTP integration.

The sender address is rejected

Symptoms: SMTP delivery is rejected, the sender is rewritten, or messages have poor delivery results.

Likely cause: The sender email configured in Supabase does not belong to a verified Volanea sending domain, or the address contains a typo.

Fix:

• Authenticate the domain in Volanea before using it in Supabase.
• Use a sender address on that exact authenticated domain.
• Check DNS records and domain verification status in Volanea.
• Ensure the sender name and sender email in Supabase are complete and correctly formatted.

For authentication email, stable sender identity matters. Changing From domains frequently makes it harder for recipients to recognize security messages and can complicate deliverability analysis.

The invitation call returns an error because await is missing

Symptoms: Your application exits early, logs a pending promise, sends a response before checking the result, or fails to handle the actual API error.

Likely cause: inviteUserByEmail() is asynchronous. Omitting await means your code does not wait for the Supabase result.

Fix: Use await inside an async-capable module or function:

const { data, error } = await supabase.auth.admin.inviteUserByEmail(
  'recipient@example.com',
  { redirectTo: 'https://app.example.com/auth/callback' }
);

The sample uses top-level await in an .mjs file. If your application uses CommonJS instead, place the call inside an async function and call that function with error handling.

The recipient gets no email, but the script says the request was accepted

Symptoms: The command prints success, yet no message appears in the inbox.

Likely cause: The request acceptance confirms the application-to-Supabase portion, not final inbox placement. The message may be delayed, filtered, rejected later in the SMTP path, sent to spam, or affected by a sender-domain configuration issue.

Fix:

1. Check spam, junk, and any corporate quarantine system.
2. Confirm the sender domain is verified in Volanea.
3. Review Volanea delivery activity for the recipient and timestamp, where available.
4. Confirm the Supabase custom SMTP settings still contain current credentials.
5. Test with another mailbox provider to distinguish recipient-specific filtering from a general setup issue.
6. Check that the recipient address is spelled correctly and is able to receive mail.

Before sending important notifications at scale, you can also verify recipient addresses before sending to reduce avoidable bounces and typo-driven failures.

The redirect URL is rejected or the invite link goes to the wrong place

Symptoms: Supabase returns a redirect-related error, the email link fails after the recipient clicks it, or a production email points to localhost.

Likely cause: The redirectTo URL is not allowed in Supabase Auth settings, or the wrong environment variable was deployed.

Fix:

• Add the exact callback URL to the allowed redirect URLs for the Supabase project.
• Use HTTPS in production.
• Maintain separate development, preview, and production environment files or secret sets.
• Log the configured redirect URL at deployment time only if doing so does not reveal sensitive information.

Do not accept a user-supplied redirect URL directly and pass it to inviteUserByEmail(). Keep redirect destinations allowlisted and controlled by your application.

You see a wrong Content-Type error in your application endpoint

Symptoms: A frontend calling your server route receives 415 Unsupported Media Type, a parsing error, or an empty request body before the server calls Supabase.

Likely cause: This happens in your own HTTP endpoint, not in the SMTP conversation. The frontend may be sending JSON without Content-Type: application/json, or your server may be parsing the request body incorrectly.

Fix: If you expose an internal endpoint that triggers invites, send JSON correctly:

await fetch('/api/invite', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ email: 'recipient@example.com' }),
});

Then parse and validate that JSON on the server before calling supabase.auth.admin.inviteUserByEmail(). Never move the secret-key Supabase call into the browser merely to avoid a server request-body issue.

A browser build exposes or blocks the secret key

Symptoms: The secret key appears in browser developer tools, your frontend build tool prefixes it into public output, or the SDK request fails because a public key is used.

Likely cause: The Auth Admin client was created in code that runs in the browser.

Fix: Move the code to a server route, backend service, worker, or protected admin function. Build a separate browser-safe client with a publishable key for normal user-facing actions. Use the secret-key client only where trusted server code executes.

An invite is sent repeatedly

Symptoms: A user receives duplicate invitation messages after retries, button clicks, or job replays.

Likely cause: The endpoint triggering invitations lacks application-level deduplication, or an operator retried after a timeout without checking whether the user was already invited.

Fix: Record an invitation request in your own database before sending, associate it with an idempotency strategy in your application workflow, and restrict who can trigger admin invites. For a public sign-up flow, use the appropriate user-facing Supabase Auth method rather than exposing an admin invitation endpoint.

Production practices for Supabase SMTP

A working test is the beginning of the implementation, not the end. Authentication messages are security-sensitive: users need them when they cannot log in, are recovering an account, or are deciding whether a message is legitimate.

Use different secrets by environment

Keep development, staging, and production separate:

Development: local Supabase project, development sender, localhost redirect URL
Staging: staging Supabase project, staging sender domain, staging callback URL
Production: production Supabase project, production sender domain, HTTPS production callback URL

Avoid pointing a local test script at production with a production secret key. Environment separation limits the impact of test mistakes and makes logs easier to interpret.

Protect the invitation trigger

The script is intentionally a server-side administrative example. In a web application, wrap equivalent code behind authorization checks. A normal signed-in user should not be able to submit an arbitrary email address and cause an admin invitation to be sent.

For example, an internal admin route may need to verify that the current operator has a specific role before it creates an invite. Apply rate limits and audit logging as well. Email actions are externally visible and can be abused for harassment, enumeration, or quota exhaustion if left unprotected.

Keep templates clear and recognizable

Supabase Auth templates should explain why the recipient received the message and what action they are being asked to take. For an invite, include recognizable product identity and avoid vague language such as “You have a message.”

Use the Supabase Auth email-template settings for message content. Test every template after you change it, particularly confirmation, recovery, and invitation templates. A malformed template can turn a correct SMTP setup into a broken user experience.

Monitor delivery signals

SMTP delivery is an operational dependency. Track the difference between:

• Auth actions requested by your application.
• Successful SMTP acceptance.
• Bounces and complaints, if reported by your email provider.
• Recipient support tickets about missing account emails.

A sudden increase in password-reset requests combined with no corresponding delivered messages may indicate a configuration issue, an authentication problem, or a recipient-side filtering change. Monitoring those signals helps you discover problems before they become widespread login failures.

Rotate credentials deliberately

Plan for secret rotation before you need it. For this integration, a safe sequence is:

1. Create or obtain replacement Volanea SMTP credentials.
2. Update Supabase custom SMTP settings with the new values.
3. Send a controlled Auth email test.
4. Confirm delivery through the expected sender domain.
5. Revoke the old Volanea SMTP credentials.
6. Rotate Supabase server secret keys separately according to your security process.

Do not rotate both systems at once without a test plan. Separating the changes makes it easier to identify which credential caused a failure.

Next steps

Once Supabase SMTP is delivering Auth email through Volanea, expand the setup in two directions.

Add delivery webhooks for operational visibility

Webhooks let your email infrastructure notify your application when delivery-related events occur. Depending on the provider and event type, these can help you record events such as delivery, bounce, complaint, or suppression-related outcomes.

Use webhooks for operational data, not as a replacement for the synchronous Supabase response. Your server should handle an invite request immediately, while webhook processing can update internal records later as delivery events arrive. Verify webhook signatures when supported, make handlers idempotent, and return quickly before handing longer processing to a queue.

Create purposeful Auth templates

Supabase Auth templates are the right place to tailor invitation, confirmation, password recovery, and magic-link content. Keep each template focused on one action, use your product’s recognizable sender identity, and test every link in each environment.

For application-generated transactional messages outside Supabase Auth—such as receipts, order status, security alerts, or product notifications—use Volanea’s standard REST or SMTP sending workflow from your backend. Keep those messages separate from Supabase-managed Auth templates so ownership, templates, and delivery diagnosis remain clear.

FAQ

Does my Node.js app send directly to Volanea in this integration?

No. The Node.js sample sends an Auth admin request to Supabase. Supabase sends the resulting email to Volanea through the custom SMTP settings you configured in the Supabase project.

Do I need a Volanea SDK to use Supabase SMTP?

No. Supabase SMTP uses the SMTP protocol, so the required provider configuration is the account-issued SMTP host, port, username, and password. The application sample uses @supabase/supabase-js because it is asking Supabase Auth to send an invitation.

Which Supabase key should I use for inviteUserByEmail()?

Use a server-only Supabase secret key. Auth admin methods require privileged credentials and must never run in browser code or be exposed to users.

Why does the example use an invitation rather than a regular email?

An invitation is a real transactional Supabase Auth email. It validates the complete custom SMTP path while also testing the invite template and callback URL. Other Auth flows, such as password recovery and confirmation, use the same custom SMTP configuration.

Can I use the same Volanea SMTP setup for password resets and magic links?

Yes. Once custom SMTP is configured for the Supabase project, Supabase Auth uses that SMTP provider for its supported Auth email flows, including messages such as invitations, confirmation emails, recovery emails, and magic links.