Documentazione per sviluppatori

Invia email via SMTP

Collega a Banger qualsiasi app che usa SMTP, da Supabase Auth a WordPress al mailer del tuo framework. La password è una chiave API Banger e ogni messaggio viene consegnato dal tuo dominio e compare nei Log.

Impostazioni

Host	`submit.bangermail.com`
Porta	`465` con TLS dall’inizio, oppure `587` con STARTTLS. Se la rete li blocca, usa `2465` (TLS) o `2587` (STARTTLS); anche la porta `25` accetta STARTTLS.
Nome utente	`banger`. Qualsiasi valore funziona: la sola chiave API identifica il tuo workspace.
Password	Una chiave API Banger con l’ambito `mail:send`.
Crittografia	TLS 1.2 o successivo. L’accesso viene offerto solo dopo l’avvio di TLS, quindi una chiave non attraversa mai la rete in chiaro.
Autenticazione	`PLAIN` o `LOGIN`.

Prima di iniziare

Crea una chiave API. In l’app Banger, apri Impostazioni → Sviluppatori → Gestisci chiavi API, scegli Crea chiave API, seleziona mail:send e copia la chiave: viene mostrata una volta. La pagina mostra queste impostazioni SMTP accanto alle chiavi.
Invia da un canale Prodotto. L’indirizzo From deve essere su un hostname con un canale Prodotto attivo, il canale per ricevute, avvisi e altre email della tua app. In Domini, scegli Aggiungi canale, poi Prodotto e aggiungi i record DNS elencati. Un canale Mail (le caselle del team) o Campagna non trasporta email dell’app, quindi la posta della tua app non può influire sulla reputazione della posta in arrivo del team.

Esempio: Supabase Auth

Nel progetto Supabase, apri Authentication → Emails → SMTP Settings e attiva SMTP personalizzato:

Email mittente	Un indirizzo sul tuo canale Prodotto, come `noreply@app.example.com`
Nome mittente	Il nome del tuo prodotto. Banger lo consegna come scritto.
Host	`submit.bangermail.com`
Porta	`465`
Nome utente	`banger`
Password	La tua chiave API

Salva, poi invia un magic link da Authentication → Users per verificare che arrivi.

Esempio: 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>",
});

Per testare da un terminale con 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

Cosa succede a ogni messaggio

Banger consegna il messaggio come scritto dalla tua app, con il tuo nome From, firmato con la chiave DKIM del tuo dominio e inviato dal dominio di bounce del tuo canale Prodotto.
Rimuove Bcc, Return-Path e gli header di Banger, e aggiunge un Reply-To che indica l’indirizzo From quando manca.
Ogni destinatario viene verificato a RCPT TO: un indirizzo escluso viene rifiutato singolarmente e gli altri ricevono l’invio.
Un messaggio può arrivare a 10 MiB con fino a 50 destinatari.
Un header Idempotency-Key rende un nuovo tentativo lo stesso invio. Anche senza, un nuovo tentativo dello stesso messaggio agli stessi destinatari viene riconosciuto.
Ogni messaggio compare in Log con SMTP come fonte e conta nel tuo piano come qualsiasi altro invio.

Risposte ed errori

Un rifiuto indica la causa e include un riferimento, (ref …), che corrisponde alla voce nei Log. I codici che iniziano con 4 sono temporanei: la tua app può riprovare più tardi.

Risposta	Significato
`535 5.7.8`	La password non è una chiave API Banger valida, la chiave è revocata o manca `mail:send`.
`421 4.7.0`	Tre accessi falliti su una connessione: viene chiusa. Verifica la chiave prima di riprovare.
`454 4.7.0`	Troppi accessi falliti dalla tua rete nell’ultima ora. Riprova più tardi.
`550 5.7.1`	L’hostname From non ha un canale Prodotto pronto all’invio (la risposta indica cosa manca), un destinatario è escluso o l’invio è in pausa per reputazione.
`553 5.1.3`	Un indirizzo del destinatario non è valido.
`552 5.3.4`	Il messaggio supera 10 MiB.
`554 5.6.0`	Il messaggio non è valido, per esempio un header From o Subject ripetuto oppure un From con più di un indirizzo.
`451 4.7.0`	La quota di invio o il limite giornaliero del workspace è esaurito. Si rinnova nel prossimo periodo di fatturazione o giorno, oppure subito con un upgrade del piano.
`451 4.3.0`	Banger non ha potuto accettare il messaggio ora. Riprova.

Sicurezza

Banger conserva solo un hash di ogni chiave. Revoca o ruota una chiave in Gestisci chiavi API; i client SMTP che la usano vengono rifiutati al prossimo accesso.
Assegna a SMTP una chiave dedicata con solo mail:send, così una password trapelata non può leggere il tuo workspace.
Gli accessi falliti sono limitati per rete client e per chiave, e un accesso rifiutato con una delle tue chiavi viene registrato nei Log.

Preferisci HTTP? Lo stesso invio è disponibile tramite API Banger.