Developer documentation

Send email over SMTP

Point any app that speaks SMTP at Banger, from Supabase Auth to WordPress to your framework's mailer. A Banger API key is the password, and every message is delivered from your own domain and appears in Logs.

Settings

Host	`submit.bangermail.com`
Port	`465` with TLS from the start, or `587` with STARTTLS. If your network blocks those, use `2465` (TLS) or `2587` (STARTTLS); port `25` also takes STARTTLS.
Username	`banger`. Any value works: the API key alone names your workspace.
Password	A Banger API key with the `mail:send` scope.
Encryption	TLS 1.2 or newer. Login is offered only after TLS starts, so a key never crosses the network in plain text.
Authentication	`PLAIN` or `LOGIN`.

Before you start

Create an API key. In the Banger app, open Settings → Developers → Manage API keys, choose Create API key, select mail:send and copy the key: it is shown once. The page shows these SMTP settings beside your keys.
Send from a Product lane. The From address must be on a hostname with an active Product lane, the lane for receipts, alerts and other email from your app. In Domains, choose Add lane, then Product, and add the DNS records it lists. A Mail lane (your team's mailboxes) or a Broadcast lane does not carry app email, so mail from your app cannot affect your team's inbox reputation.

Example: Supabase Auth

In your Supabase project, open Authentication → Emails → SMTP Settings and enable custom SMTP:

Sender email	An address on your Product lane, such as `noreply@app.example.com`
Sender name	Your product's name. Banger delivers it as written.
Host	`submit.bangermail.com`
Port	`465`
Username	`banger`
Password	Your API key

Save, then send a magic link from Authentication → Users to check it arrives.

Example: Node.js

import nodemailer from "nodemailer";

const transport = nodemailer.createTransport({
  host: "submit.bangermail.com",
  port: 465,
  secure: true,
  auth: { user: "banger", pass: process.env.BANGER_API_KEY },
});

await transport.sendMail({
  from: "Acme <noreply@app.example.com>",
  to: "person@example.com",
  subject: "Your receipt",
  html: "<p>Thanks for your order.</p>",
});

To test from a terminal with swaks:

swaks --server submit.bangermail.com:465 --tls-on-connect \
  --auth PLAIN --auth-user banger --auth-password "$BANGER_API_KEY" \
  --from noreply@app.example.com --to you@example.com

What happens to each message

Banger delivers the message as your app wrote it, with your From name, signed with your domain's DKIM key and sent from your Product lane's bounce domain.
It removes Bcc, Return-Path and Banger's own headers, and adds a Reply-To naming the From address when there is none.
Each recipient is checked at RCPT TO: a suppressed address is refused on its own and the others are sent.
A message can be up to 10 MiB with up to 50 recipients.
An Idempotency-Key header makes a retry the same send. Without one, a retry of the same message and recipients is still recognized.
Every message appears in Logs with SMTP as its source, and counts toward your plan like any other send.

Replies and errors

A refusal names its cause and carries a reference, (ref …), that matches the entry in Logs. Codes starting with 4 are temporary: your app can retry later.

Reply	Meaning
`535 5.7.8`	The password is not a valid Banger API key, the key is revoked, or it lacks `mail:send`.
`421 4.7.0`	Three failed logins on one connection: it closes. Check the key before retrying.
`454 4.7.0`	Too many failed logins from your network in the last hour. Try again later.
`550 5.7.1`	The From hostname has no Product lane ready to send (the reply says what it lacks), a recipient is suppressed, or sending is paused for reputation.
`553 5.1.3`	A recipient address is not valid.
`552 5.3.4`	The message is larger than 10 MiB.
`554 5.6.0`	The message is malformed, for example a repeated From or Subject header, or a From with more than one address.
`451 4.7.0`	The workspace's sending allowance or daily limit is used up. It renews with the next billing period or day, or now with a plan upgrade.
`451 4.3.0`	Banger could not take the message right now. Retry.

Security

Banger stores only a hash of each key. Revoke or rotate a key in Manage API keys; SMTP clients using it are refused at their next login.
Give SMTP its own key with only mail:send, so a leaked password cannot read your workspace.
Failed logins are limited per client network and per key, and a refused login with one of your keys is recorded in Logs.

Prefer HTTP? The same sending is available through the Banger API.