Skip to content
Invitation-only alpha. Features and limits may change as we learn from testing.

First send via SMTP

  • A project with a connected domain and sending permission for your sender address.
  • An SMTP credential for that sender: a username starting with smtp_ and a password shown once. SMTP credentials only send; they can’t call the API.

The credential’s View SMTP settings page shows these values filled in, with examples.

Open API keys & SMTP → View SMTP settings. Copy the SMTP test command, replace you@example.com with your inbox, then run it. curl asks for the SMTP password you saved. Host, encryption, username and sender are filled in; Node.js is not needed.

The command contains a fixed message ID and date, so you can reuse the exact command if a retry is needed. First check Messages if the result is unclear. Keep the same recipient on retries. Connection settings and Nodemailer/GoTrue examples are under Connection settings and application examples.

Setting Value
Host smtp.weneed.email
Port 587 with STARTTLS, or 465 with implicit TLS
Encryption required, TLS 1.2 or newer; keep certificate verification on
Authentication PLAIN or LOGIN, only after TLS
From must exactly match the sender address on your SMTP login
import { createHash } from 'node:crypto';
import nodemailer from 'nodemailer';
// One key per intended message. Store it, and the time of the first attempt, with the event,
// so a retry sends exactly the same message.
const key = 'signup-7f3c2a91-welcome';
const firstAttempt = new Date(storedFirstAttemptTime);
const messageId = `<${createHash('sha256').update(key).digest('hex')}@yourdomain.com>`;
const transport = nodemailer.createTransport({
host: 'smtp.weneed.email',
port: 587,
secure: false, // STARTTLS is negotiated on 587; use 465 with secure: true for implicit TLS
requireTLS: true,
tls: { minVersion: 'TLSv1.2' },
auth: { user: process.env.WENEED_SMTP_USER, pass: process.env.WENEED_SMTP_PASSWORD },
});
const info = await transport.sendMail({
from: 'hello@yourdomain.com',
to: 'person@example.com',
subject: 'Welcome',
text: 'Thanks for signing up.',
messageId,
date: firstAttempt,
headers: { 'X-Email-Idempotency-Key': key },
});
console.log(info.response);

A 250 reply means the message is stored and queued, not delivered.

Ordinary mail clients retry on their own. If the connection drops after you sent the message but before the 250 arrived, a retry can create a second message. Add the X-Email-Idempotency-Key header (16 to 128 printable characters) so a retry of the same message is recognised.

A retry must be exactly the same message, including Message-ID and Date. Most libraries create new ones for every attempt, which is why the example sets both. A retry with the same key but different content is refused with 550 and not sent. See Retries and duplicates.

Using Supabase Auth? See Supabase Auth over SMTP.

One recipient per message, no attachments, and no sent folder or inbox. Full limits are in the SMTP reference.