SMTP relay

Connect any app, mail client, or Postfix relayhost to smtp.hep.gg:587. The key is the AUTH password; the username is ignored.

SMTP relay#

The SMTP relay lets an app you already have send mail through Hep.gg without code changes: point its mail transport at smtp.hep.gg, authenticate with a hyd-mail- key, and send. Every message runs through the same pipeline as the HTTPS API, so it draws on the same credits, daily caps, and send log.

Connection details#

Client examples#

The transport stays the same across languages: host smtp.hep.gg, port 587, STARTTLS on, password = your key.

import nodemailer from "nodemailer";
 
const transporter = nodemailer.createTransport({
  host: "smtp.hep.gg",
  port: 587,
  secure: false,        // STARTTLS upgrade happens automatically
  requireTLS: true,
  auth: { user: "x", pass: process.env.HEPGG_EMAIL_KEY }, // user is ignored
});
 
await transporter.sendMail({
  from: '"Acme" <noreply@hep.gg>',
  to: "customer@example.com",
  subject: "Receipt #12345",
  html: "<h1>Thanks!</h1><p>Your receipt is attached below.</p>",
});

import smtplib, ssl, os
from email.mime.text import MIMEText
 
msg = MIMEText("<h1>Hi!</h1>", "html")
msg["Subject"] = "Receipt #12345"
msg["From"] = "noreply@hep.gg"
msg["To"] = "customer@example.com"
 
with smtplib.SMTP("smtp.hep.gg", 587) as s:
    s.starttls(context=ssl.create_default_context())
    s.login("x", os.environ["HEPGG_EMAIL_KEY"])  # user is ignored; key is the password
    s.send_message(msg)

swaks --to customer@example.com \
  --from noreply@hep.gg \
  --server smtp.hep.gg:587 \
  --tls \
  --auth LOGIN \
  --auth-user x \
  --auth-password "$HEPGG_EMAIL_KEY" \
  --header "Subject: Receipt #12345" \
  --body "Welcome to Acme."

Sender (From:) selection#

The relay reads the From: header to pick which sender address to authenticate through. That address must be one your account is allowed to send from: the global noreply@hep.gg (available to everyone), or an address Hep.gg has assigned to you. A display name is honored and truncated to 100 characters, so "Acme Receipts" <noreply@hep.gg> is fine.

If the From: header is absent, the relay falls back to the MAIL FROM envelope address, then to your account default sender. Sending from an address you do not own is rejected, and no credit is charged. See Senders, billing & limits for the full address rules.

Recipients: To, Cc, and Bcc#

The relay builds the recipient set from both the message headers and the SMTP envelope:

• To and Cc come from the To: and Cc: headers.
• Bcc should be supplied as envelope-only RCPT TO addresses, that is, recipients in the envelope that do not appear in the visible headers. A Bcc: header is also honored if present, but envelope-only RCPT TO is the reliable way to blind-copy. Most mail libraries do this for you when you set Bcc.

Billing counts every distinct recipient across To, Cc, and Bcc (de-duplicated, case-insensitive), at one credit each. The combined total is capped at 100 recipients per message.

Size limits#

Two ceilings apply to SMTP:

• 30 MB raw message ceiling. The server hard-kills any message larger than 30 MB including headers and base64 encoding overhead.
• 10 MB decoded body cap. After parsing, the combined HTML plus text body must be under 10 MB. This is the same cap the HTTPS API enforces.

The 30 MB raw figure exists so a 10 MB body still fits once MIME headers and base64 inflation (roughly 33 percent) are added.

Response codes#

On accept, the DATA command returns 250 with the message id, for example 250 OK: a1b2c3d4e5f6a7b8 (or 250 queued: ... when a per-address daily cap forced the message into the retry queue). That id matches the Logs tab row.

Rejections map the internal pipeline result onto SMTP reply codes. See Errors & retries for the full mapping. In short:

• Rate limit exceeded -> 421 (transient, retry later)
• Insufficient credits -> 451 (retry after topping up)
• Bad or disabled key -> 535 (fails at AUTH, before DATA)
• Unauthorized sender, invalid body, oversize, or relay failure -> 550

Credits are never charged for a terminal failure; the request is refunded automatically.