Markdown

SMTP relay

Send mail through Groundmail using standard SMTP — for Supabase custom SMTP, WordPress, Nodemailer, and other integrations that expect host, username, and password. For field-by-field setup in tools like Knock, Courier and Novu, see Tools with SMTP settings.

Updated Nov 17, 20264 min read

The relay uses the same account scoping, domain verification, sandbox rules, billing, suppressions, and webhooks as POST /emails.

Connection settings

Setting Value
Host smtp.groundmail.dev
Port 587 (STARTTLS), or 2525 if your host blocks 587
Username groundmail
Password Your SMTP credential (gmsmtp_…)

Port 2525 is the same server with the same STARTTLS and login. Use it when your host blocks outbound 587: DigitalOcean and Vultr block it on new accounts, and Railway and Render block SMTP on their free plans (on those two, send over HTTPS instead: see Railway).

Create credentials in the dashboard under SMTP or via POST /smtp-credentials with a full-access API key.

The password is shown once at creation — copy it immediately.

Create a credential

Response includes host, port, username, test, and password.

Terminal
curl -X POST https://api.groundmail.dev/smtp-credentials \
  -H "Authorization: Bearer $GROUNDMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Supabase production"}'

Test credentials

Add "test": true to get a test credential, with a password that starts gmsmtp_test_. It works like a test key: your app connects to the same host with the same username, but every message is simulated. Nothing is delivered, a copy lands in your test inbox, and it doesn't count toward your plan, limits or stats. Use one for staging apps and CI.

Real addresses follow the same limits as a live send: until you verify a domain and add a payment method, anything but your account email is refused with 554. Simulator addresses work on any plan: send to bounce@simulator.groundmail.dev to see a bounce over SMTP. In the dashboard, switch to Test and open SMTP. GET /smtp-credentials?test=true lists test credentials only; each credential has a test field.

Terminal
curl -X POST https://api.groundmail.dev/smtp-credentials \
  -H "Authorization: Bearer $GROUNDMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Supabase staging","test":true}'

Email category

Groundmail reads each email and decides whether it's transactional or product, which picks its sending stream. There's nothing to set for that: a credential's transactional or product category, and an X-Groundmail-Category header with those values, are deprecated, accepted and ignored. The one category you still set is newsletter, for opt-in newsletters on an approved account: on the credential, so every email sent with it is a newsletter, or per email with the header.

Use one credential per kind of mail. For example, a "Newsletter" credential in your newsletter tool and a separate one for password resets and receipts.

  • Dashboard: choose Newsletter as the Category when you create the credential, or open a credential's ⋯ menu and choose Change category. The password stays the same, so the app keeps working and the next email uses the new category. Detected by Groundmail is everything else.
  • API: pass category to POST /smtp-credentials, or change it with PATCH /smtp-credentials/{id}. null clears it.

If your code can set headers, add X-Groundmail-Category: newsletter to an email instead, so one credential can send newsletters and everything else.

newsletter is for accounts approved for newsletter sending. Setting it on a credential, or sending with it, from an account that isn't approved is refused with newsletter_not_enabled (554 over SMTP), and nothing is sent. Newsletter email always gets one-click unsubscribe.

Terminal
curl -X PATCH https://api.groundmail.dev/smtp-credentials/$CREDENTIAL_ID \
  -H "Authorization: Bearer $GROUNDMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"category":"newsletter"}'

Who the message is from

The message needs exactly one From header naming one address on a domain verified on your team. The address in MAIL FROM has to be on a verified domain too. Anything else is refused with 554 and a reason, and nothing is sent.

Who the message goes to

Every address in To, Cc and Bcc has to be a single mailbox. A group, an entry with no address, or angle brackets in a display name is refused with 554 and a reason, and nothing is sent. So is a RCPT TO that isn't one plain address.

Supabase custom SMTP

After you verify your domain in Groundmail:

  1. Dashboard → SMTP → Create SMTP credential
  2. Supabase → Project Settings → Authentication → SMTP
  3. Paste host, port, username groundmail, password, and your branded sender email

For hook-based auth mail (Edge Functions), see Supabase Auth email.

Nodemailer example (SMTP)

For the HTTP Nodemailer transport (no SMTP credential), see Node.js.

JavaScript
import nodemailer from 'nodemailer'

const transport = nodemailer.createTransport({
  host: 'smtp.groundmail.dev',
  port: 587,
  secure: false,
  auth: {
    user: 'groundmail',
    pass: process.env.GROUNDMAIL_SMTP_PASSWORD,
  },
})

await transport.sendMail({
  from: 'noreply@yourdomain.com',
  to: 'user@example.com',
  subject: 'Hello',
  html: '<p>Hi</p>',
  headers: {
    'X-Groundmail-Tag': 'campaign=welcome',
    'X-Groundmail-Idempotency-Key': 'welcome-123',
    // 'X-Groundmail-Category': 'newsletter', // approved accounts only
    // 'X-Groundmail-Scheduled-At': '2030-01-01T00:00:00Z',
  },
})

Custom headers (API features over SMTP)

The relay maps these headers onto POST /emails fields so SMTP clients are not limited to basic MIME:

Header Maps to
X-Groundmail-Tag tags (name=value; repeat for multiple)
X-Groundmail-Idempotency-Key or Idempotency-Key Idempotency (24h, same rules as HTTP)
X-Groundmail-Scheduled-At scheduled_at (ISO 8601)
X-Groundmail-Category newsletter sends an opt-in newsletter (approved accounts). transactional and product are deprecated and ignored: Groundmail decides (category).

Other non-reserved headers are forwarded to the API headers object.

Headers the mail server sets itself are ignored, not refused: Return-Path, Sender, Received, DKIM-Signature, Authentication-Results, Delivered-To and the Resent-* headers. Some mail libraries add Return-Path on their own, and the message still sends. Bounces come back to Groundmail, which records them and tells you by webhook.

Rules

  • From must use a verified domain for your account (or sandbox rules apply)
  • Revoke credentials from the dashboard or DELETE /smtp-credentials/{id}
  • Rename a credential or change its category with PATCH /smtp-credentials/{id}
  • SMTP credentials are send-only — use API keys for management APIs
  • Each message counts against the same send limits as the API, including a new account's daily ramp-up limit. A message over the Free plan's limit is rejected with a permanent 554 reply that says which limit was reached. A message over a new account's daily ramp-up limit gets a temporary 451 4.7.1 reply with the reset time (retry after <time>), so your mail server keeps it queued and retries after 00:00 UTC.
  • A message can be at most 20MB, attachments included. The relay advertises the limit (SIZE in its EHLO reply) and refuses a larger message with a permanent 552 5.3.4 reply. Each attachment can be up to 10MB, as on the API.

Was this page helpful?