Relay SMTP

Il relay SMTP permette al software che parla solo SMTP (CMS, provider di autenticazione, framework, app legacy) di inviare tramite SpacePost. I messaggi passano per la stessa pipeline dell’API: controlli sul dominio, lista di soppressione, quote, tracciamento, webhook.

Impostazione	Valore
Host	`smtp.spacepost.dev`
Porta	`25976`
Sicurezza	STARTTLS, obbligatorio prima dell’autenticazione
Nome utente	`spacepost` (è accettato anche l’alias `resend`, per le migrazioni)
Password	La tua chiave API (`sp_live_...`)

Connettiti senza TLS e passa a TLS con STARTTLS prima del login; il certificato è valido per smtp.spacepost.dev. Il TLS implicito (porta 465) non è ancora disponibile, quindi nella maggior parte dei client scegli “STARTTLS” o “TLS”, non “SSL”.

L’indirizzo From deve appartenere a un dominio verificato. Una chiave sending_access basta; una chiave limitata a un dominio può inviare solo da quel dominio.

Header di controllo

Aggiungi questi header al tuo messaggio per usare funzionalità per cui SMTP non ha un campo. Vengono consumati da SpacePost e non consegnati al destinatario.

Header	Esempio	Effetto
`X-SpacePost-Tags`	`category=welcome, user_id=u_1042`	Aggiunge i tag. Coppie `name=value` separate da virgole; stesse regole sui caratteri dell’API.
`X-SpacePost-Scheduled-At`	`2026-11-01T09:00:00Z` o `in 1 hour`	Pianifica l’email (fino a 30 giorni).

Gli altri header X-*, List-Unsubscribe, List-Unsubscribe-Post, In-Reply-To e References vengono inoltrati come header personalizzati.

Esempi

import nodemailer from "nodemailer";

const transport = nodemailer.createTransport({
  host: "smtp.spacepost.dev",
  port: 25976,
  secure: false, // STARTTLS: the connection is upgraded to TLS before login
  requireTLS: true,
  auth: { user: "spacepost", pass: process.env.SPACEPOST_API_KEY },
});

await transport.sendMail({
  from: "Acme <hello@acme.com>",
  to: "user@example.com",
  subject: "Hello over SMTP",
  html: "<p>It works.</p>",
  headers: { "X-SpacePost-Tags": "category=welcome", "X-SpacePost-Scheduled-At": "in 10 minutes" },
});

import os, smtplib
from email.message import EmailMessage

msg = EmailMessage()
msg["From"] = "Acme <hello@acme.com>"
msg["To"] = "user@example.com"
msg["Subject"] = "Hello over SMTP"
msg["X-SpacePost-Tags"] = "category=welcome"
msg.set_content("It works.")
msg.add_alternative("<p>It works.</p>", subtype="html")

with smtplib.SMTP("smtp.spacepost.dev", 25976) as s:
    s.starttls()
    s.login("spacepost", os.environ["SPACEPOST_API_KEY"])
    s.send_message(msg)

swaks --server smtp.spacepost.dev --port 25976 --tls \
  --auth-user spacepost --auth-password "$SPACEPOST_API_KEY" \
  --from hello@acme.com --to delivered@test.spacepost.dev \
  --header "Subject: Hello" --header "X-SpacePost-Tags: category=test" --body "It works."

Come vengono mappati i messaggi

To, Cc e Reply-To vengono presi dagli header. I destinatari della busta (RCPT TO) che non sono in To o Cc diventano Bcc.
Le parti HTML e testo vengono mantenute. Gli allegati, comprese le immagini inline (Content-ID), sono supportati.
Un messaggio senza oggetto riceve l’oggetto (no subject).
Ogni destinatario conta sulla tua quota, come con l’API.

Limiti e codici di errore

Limite	Valore
Dimensione del messaggio	40 MB, risposta `552`
Errori di autenticazione	10 tentativi falliti per IP in 10 minuti, poi blocco

Le risposte SMTP corrispondono agli errori dell’API:

Situazione	Risposta
Quota giornaliera o mensile superata	`452` (temporaneo: il tuo software riproverà più tardi)
Limite di frequenza	`421`
Dominio `From` non verificato	`553`
Chiave limitata, team in pausa, errori di validazione, contenuto bloccato	`550`
Problema temporaneo da parte nostra	`451`

Guide per i framework