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.
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.
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
categorytoPOST /smtp-credentials, or change it withPATCH /smtp-credentials/{id}.nullclears 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.
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:
- Dashboard → SMTP → Create SMTP credential
- Supabase → Project Settings → Authentication → SMTP
- 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.
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
Frommust 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
554reply that says which limit was reached. A message over a new account's daily ramp-up limit gets a temporary451 4.7.1reply 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 (
SIZEin itsEHLOreply) and refuses a larger message with a permanent552 5.3.4reply. Each attachment can be up to 10MB, as on the API.