First send via SMTP
You need
Section titled “You need”- 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.
Quick terminal test
Section titled “Quick terminal test”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.
Settings
Section titled “Settings”| 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 |
Example with Nodemailer
Section titled “Example with Nodemailer”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.
Avoid duplicates
Section titled “Avoid duplicates”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.
What SMTP doesn’t do
Section titled “What SMTP doesn’t do”One recipient per message, no attachments, and no sent folder or inbox. Full limits are in the SMTP reference.