API e SMTP di SMTP Senpai

Tre modi per spedire

Portano tutti agli stessi server, con la stessa firma DKIM sul tuo dominio, lo stesso registro e la stessa lista di soppressione. Scegli in base a cosa hai già.

Prima di spedire serve un dominio verificato: nell'area cliente trovi i record DNS da pubblicare (servono a firmare le email con DKIM sul tuo dominio) e li controlliamo noi. Il mittente di ogni email deve stare su quel dominio o su un suo sottodominio.

Autenticazione

Ogni chiamata all'API porta la tua chiave nell'intestazione Authorization: Bearer msp_…. La chiave inizia con msp_ ed è lunga 52 caratteri: la trovi nell'area cliente, pagina SMTP Senpai, riquadro Chiave per le tue applicazioni.

Authorization: Bearer msp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

• Rigenerandola dall'area cliente, quella vecchia smette subito di funzionare.
• Tienila sul server, in una variabile d'ambiente: l'API non accetta chiamate dai browser (non invia intestazioni CORS), così la chiave non finisce nel codice di una pagina web. Per i form dei siti c'è l'indirizzo dei moduli, che non richiede chiave.
• Se la tua piattaforma non permette intestazioni personalizzate, puoi passare la chiave nel campo chiave del corpo (JSON o form). Per le richieste GET si accetta anche come parametro dell'indirizzo, ma è sconsigliato: gli indirizzi finiscono nei registri dei server e dei proxy.
• Le credenziali SMTP (utente e password) sono diverse dalla chiave API e si cambiano separatamente.

Chiave mancante o sbagliata:

{
  "ok": false,
  "errore": "chiave non valida"
}

Il primo invio in un minuto

1. Verifica il dominio da cui spedirai (area cliente, pagina Domini). Se hai appena attivato la prova, è il dominio che hai indicato all'iscrizione.
2. Copia la chiave e mettila in una variabile d'ambiente: export SMTPSENPAI_CHIAVE=msp_…
3. Lancia questa richiesta, con un destinatario tuo e un mittente sul dominio verificato:

curl https://app.mailsenpai.com/relay/v1/invio \
  -H "Authorization: Bearer $SMTPSENPAI_CHIAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "a": "cliente@esempio.it",
    "da": "ordini@tuodominio.it",
    "oggetto": "Prova da SMTP Senpai",
    "testo": "Funziona!"
  }'

Se tutto è a posto la risposta è questa, e in pochi secondi l'email è nella casella:

{
  "ok": true,
  "inviato": true,
  "id_messaggio": "9f2c4e1a7b3d5f6e8a9b0c1d@tuodominio.it",
  "residuo": 8759,
  "oltre_il_piano": false
}

Conserva id_messaggio: è anche il Message-ID dell'email e ti serve per ritrovarla nel registro.

Esempi pronti: Node, Python, PHP

Per ogni linguaggio c'è la versione con l'API REST e quella via SMTP. Gli esempi leggono chiave, utente e password da variabili d'ambiente: SMTPSENPAI_CHIAVE, SMTPSENPAI_UTENTE, SMTPSENPAI_PASSWORD.

// Node.js 18+: fetch è già incluso
async function inviaEmail() {
  const risposta = await fetch('https://app.mailsenpai.com/relay/v1/invio', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.SMTPSENPAI_CHIAVE}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      a: 'cliente@esempio.it',
      da: 'ordini@tuodominio.it',
      nome_mittente: 'Il tuo negozio',
      oggetto: 'Conferma ordine 10293',
      html: '<p>Grazie, il tuo ordine è confermato.</p>',
      rispondi_a: 'assistenza@tuodominio.it',
    }),
  });
  const esito = await risposta.json();
  if (!esito.ok) {
    throw new Error(`${risposta.status}: ${esito.errore}`);
  }
  console.log(esito.inviato ? `Inviata: ${esito.id_messaggio}` : `Non inviata: ${esito.motivo}`);
}

inviaEmail().catch((e) => { console.error(e.message); process.exitCode = 1; });

// npm install nodemailer
const nodemailer = require('nodemailer');

const transporter = nodemailer.createTransport({
  host: 'relay.mailsenpai.com',
  port: 2525,
  secure: false,      // si parte in chiaro...
  requireTLS: true,   // ...e si passa subito a STARTTLS
  auth: {
    user: process.env.SMTPSENPAI_UTENTE,
    pass: process.env.SMTPSENPAI_PASSWORD,
  },
});

async function inviaEmail() {
  const info = await transporter.sendMail({
    from: '"Il tuo negozio" <ordini@tuodominio.it>',
    to: 'cliente@esempio.it',
    subject: 'La tua fattura',
    text: 'In allegato trovi la fattura.',
    html: '<p>In allegato trovi la fattura.</p>',
    attachments: [{ filename: 'fattura.pdf', path: './fattura.pdf' }],
  });
  console.log('Accettata:', info.messageId);
}

inviaEmail().catch((e) => { console.error(e.message); process.exitCode = 1; });

# pip install requests
import os
import requests

risposta = requests.post(
    "https://app.mailsenpai.com/relay/v1/invio",
    headers={"Authorization": f"Bearer {os.environ['SMTPSENPAI_CHIAVE']}"},
    json={
        "a": "cliente@esempio.it",
        "da": "ordini@tuodominio.it",
        "nome_mittente": "Il tuo negozio",
        "oggetto": "Conferma ordine 10293",
        "html": "<p>Grazie, il tuo ordine è confermato.</p>",
        "testo": "Grazie, il tuo ordine è confermato.",
    },
    timeout=30,
)
esito = risposta.json()
if not esito["ok"]:
    raise RuntimeError(f"{risposta.status_code}: {esito['errore']}")
print(esito["id_messaggio"] if esito["inviato"] else esito["motivo"])

import os
import smtplib
from email.message import EmailMessage

msg = EmailMessage()
msg["From"] = "Il tuo negozio <ordini@tuodominio.it>"
msg["To"] = "cliente@esempio.it"
msg["Subject"] = "La tua fattura"
msg.set_content("In allegato trovi la fattura.")
msg.add_alternative("<p>In allegato trovi la fattura.</p>", subtype="html")
with open("fattura.pdf", "rb") as allegato:
    msg.add_attachment(allegato.read(), maintype="application",
                       subtype="pdf", filename="fattura.pdf")

with smtplib.SMTP("relay.mailsenpai.com", 2525, timeout=30) as server:
    server.starttls()
    server.login(os.environ["SMTPSENPAI_UTENTE"], os.environ["SMTPSENPAI_PASSWORD"])
    server.send_message(msg)

<?php
$ch = curl_init('https://app.mailsenpai.com/relay/v1/invio');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT        => 30,
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer ' . getenv('SMTPSENPAI_CHIAVE'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS     => json_encode([
        'a' => 'cliente@esempio.it',
        'da' => 'ordini@tuodominio.it',
        'nome_mittente' => 'Il tuo negozio',
        'oggetto' => 'Conferma ordine 10293',
        'html' => '<p>Grazie, il tuo ordine è confermato.</p>',
    ], JSON_UNESCAPED_UNICODE),
]);
$body   = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

$esito = json_decode((string) $body, true);
if (empty($esito['ok'])) {
    throw new RuntimeException($status . ': ' . ($esito['errore'] ?? 'risposta non valida'));
}
echo $esito['inviato'] ? $esito['id_messaggio'] : $esito['motivo'];

<?php
// composer require phpmailer/phpmailer
use PHPMailer\PHPMailer\PHPMailer;

require 'vendor/autoload.php';

$mail = new PHPMailer(true);
$mail->isSMTP();
$mail->Host       = 'relay.mailsenpai.com';
$mail->Port       = 2525;
$mail->SMTPAuth   = true;
$mail->SMTPSecure = PHPMailer::ENCRYPTION_STARTTLS;
$mail->Username   = getenv('SMTPSENPAI_UTENTE');
$mail->Password   = getenv('SMTPSENPAI_PASSWORD');
$mail->CharSet    = 'UTF-8';

$mail->setFrom('ordini@tuodominio.it', 'Il tuo negozio');
$mail->addAddress('cliente@esempio.it');
$mail->Subject = 'La tua fattura';
$mail->isHTML(true);
$mail->Body    = '<p>In allegato trovi la fattura.</p>';
$mail->AltBody = 'In allegato trovi la fattura.';
$mail->addAttachment('fattura.pdf');
$mail->send();

Nell'area cliente, nel riquadro Esempi pronti, trovi anche la configurazione per WordPress (WP Mail SMTP o FluentSMTP) già compilata con i tuoi dati.

SDK e librerie

Preferisci una libreria alle chiamate HTTP dirette? I pacchetti ufficiali usano questa API: npm install @mailsenpai/smtp-senpai (Node.js), npm install @mailsenpai/nestjs (NestJS), pip install mailsenpai (Python, con il backend per Django), gem install mailsenpai (Ruby e Rails, su RubyGems), composer require mailsenpai/symfony-mailer symfony/http-client (Symfony) e composer require mailsenpai/laravel (Laravel). I pacchetti per Strapi, Payload, Medusa, Directus, n8n e Activepieces (@mailsenpai/activepieces-piece-smtp-senpai, su npm), con i collegamenti ai registri e al codice sorgente su GitLab, sono nella pagina Integrazioni.

Riferimento endpoint

Indirizzo base https://app.mailsenpai.com/relay/v1. Tutte le risposte sono JSON con il campo ok. I messaggi di errore sono in italiano.

curl https://app.mailsenpai.com/relay/v1/invio \
  -H "Authorization: Bearer $SMTPSENPAI_CHIAVE" \
  -H "Idempotency-Key: ordine-10293" \
  -H "Content-Type: application/json" \
  -d '{
    "a": ["cliente@esempio.it", "amministrazione@esempio.it"],
    "da": "ordini@tuodominio.it",
    "oggetto": "La tua fattura",
    "testo": "In allegato trovi la fattura.",
    "allegati": [{"nome": "fattura.pdf", "contenuto": "JVBERi0xLjQK...", "tipo": "application/pdf"}]
  }'

{
  "ok": true,
  "inviati": 2,
  "non_inviati": 0,
  "risultati": [
    {"a": "cliente@esempio.it", "inviato": true, "id_messaggio": "9f2c4e1a7b3d5f6e8a9b0c1d@tuodominio.it"},
    {"a": "amministrazione@esempio.it", "inviato": true, "id_messaggio": "1b7e0d2f4a6c8e9b3d5f7a1c@tuodominio.it"}
  ],
  "residuo": 8757,
  "oltre_il_piano": false
}

curl https://app.mailsenpai.com/relay/v1/invio \
  -H "Authorization: Bearer $SMTPSENPAI_CHIAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "a": "cliente@esempio.it",
    "da": "ordini@tuodominio.it",
    "oggetto": "Prova da SMTP Senpai",
    "testo": "Funziona!"
  }'

{
  "ok": true,
  "inviato": false,
  "motivo": "indirizzo nella lista di soppressione"
}

curl https://app.mailsenpai.com/relay/v1/stato \
  -H "Authorization: Bearer $SMTPSENPAI_CHIAVE"

{
  "ok": true,
  "stato": "active",
  "smtp": {
    "server": "relay.mailsenpai.com",
    "porta": 2525,
    "porta_alternativa": 2525,
    "utente": "r1234@tuodominio.it",
    "sicurezza": "STARTTLS"
  },
  "volume": {
    "mese": "2026-10",
    "incluso": 10000,
    "usato": 1240,
    "residuo": 8760,
    "per_ora": 400
  },
  "tracciamento": false,
  "soppressi": 17
}

curl "https://app.mailsenpai.com/relay/v1/statistiche?giorni=7" \
  -H "Authorization: Bearer $SMTPSENPAI_CHIAVE"

{
  "ok": true,
  "giorni": 7,
  "dati": {
    "sent": 812,
    "delivered": 798,
    "bounce": 9,
    "defer": 14,
    "complaint": 0,
    "tracciamento": "non attivo: ...",
    "tasso_consegna": 98.3,
    "tasso_rimbalzo": 1.11,
    "tasso_segnalazioni": 0.0
  },
  "per_giorno": {
    "2026-09-30": { "delivered": 120, "bounce": 2 },
    "2026-10-01": { "sent": 95, "delivered": 93 }
  }
}

curl "https://app.mailsenpai.com/relay/v1/eventi?tipo=bounce&quanti=20" \
  -H "Authorization: Bearer $SMTPSENPAI_CHIAVE"

{
  "ok": true,
  "eventi": [
    {
      "event_id": "88213",
      "relay_id": "12",
      "type": "bounce",
      "email": "mario@esempio.it",
      "domain": "esempio.it",
      "from_domain": "tuodominio.it",
      "code": "550",
      "reason": "5.1.1 user unknown",
      "message_id": "",
      "url": "",
      "happened_at": "2026-10-01 08:42:10"
    }
  ]
}

curl "https://app.mailsenpai.com/relay/v1/eventi?dopo=88213&quanti=100" \
  -H "Authorization: Bearer $SMTPSENPAI_CHIAVE"

{
  "ok": true,
  "eventi": [ { "event_id": 88214, "type": "delivered", "email": "mario@esempio.it", "...": "..." } ],
  "prossimo": "88214",
  "altri": false
}

curl "https://app.mailsenpai.com/relay/v1/soppressi?cerca=esempio.it" \
  -H "Authorization: Bearer $SMTPSENPAI_CHIAVE"

{
  "ok": true,
  "totale": 2,
  "elenco": [
    { "supp_id": "501", "relay_id": "12", "email": "mario@esempio.it",
      "reason": "bounce", "note": "5.1.1 user unknown", "created_at": "2026-10-01 08:42:10" },
    { "supp_id": "488", "relay_id": "12", "email": "@concorrente.it",
      "reason": "manuale", "note": "", "created_at": "2026-09-20 10:00:00" }
  ]
}

curl https://app.mailsenpai.com/relay/v1/sopprimi \
  -H "Authorization: Bearer $SMTPSENPAI_CHIAVE" \
  -H "Content-Type: application/json" \
  -d '{"email": "mario@esempio.it", "nota": "ha chiesto di non essere contattato"}'

curl https://app.mailsenpai.com/relay/v1/riammetti \
  -H "Authorization: Bearer $SMTPSENPAI_CHIAVE" \
  -H "Content-Type: application/json" \
  -d '{"email": "mario@esempio.it"}'

Webhook: gli esiti in tempo reale

Invece di leggere /eventi a intervalli, puoi farti avvisare: a ogni evento del tuo account mandiamo un POST JSON all'indirizzo https che scegli. Un evento per chiamata, così funziona anche con Zapier, Make e n8n. Lo imposti nell'area cliente, riquadro Avvisi in tempo reale, oppure con l'API qui sotto.

Il corpo della chiamata

{
  "id": "evt_88214",
  "type": "delivered",
  "created_at": "2026-10-09T10:26:01Z",
  "data": {
    "email": "mario@esempio.it",
    "domain": "esempio.it",
    "from_domain": "tuodominio.it",
    "code": "2.0.0",
    "reason": "",
    "message_id": "9f2c4e1a7b3d5f6e8a9b0c1d@tuodominio.it",
    "url": ""
  },
  "account": "codice-del-tuo-account"
}

Rispondi con un codice 2xx entro 8 secondi. Se il tuo server non risponde o dà un errore riproviamo dopo 1 minuto, 5 minuti, 30 minuti, 2, 6 e 12 ore: circa 24 ore in tutto. Accettiamo solo indirizzi https pubblici.

Verificare la firma

import crypto from 'node:crypto';

// corpo grezzo della richiesta (stringa) e intestazione X-MailSenpai-Signature
function firmaValida(body, header, secret) {
  const m = /t=(\d+),v1=([a-f0-9]+)/.exec(header || '');
  if (!m) return false;
  if (Math.abs(Date.now() / 1000 - Number(m[1])) > 300) return false; // max 5 minuti
  const atteso = crypto.createHmac('sha256', secret).update(`${m[1]}.${body}`).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(atteso), Buffer.from(m[2]));
}

<?php
$body = file_get_contents('php://input');
$sig = $_SERVER['HTTP_X_MAILSENPAI_SIGNATURE'] ?? '';
$secret = getenv('MAILSENPAI_WEBHOOK_SECRET');
if (!preg_match('/t=(\d+),v1=([a-f0-9]+)/', $sig, $m) || abs(time() - (int) $m[1]) > 300
    || !hash_equals(hash_hmac('sha256', $m[1] . '.' . $body, $secret), $m[2])) {
    http_response_code(401); exit;
}
$evento = json_decode($body, true);
http_response_code(200);

import hmac, hashlib, re, time

def firma_valida(body: bytes, header: str, secret: str) -> bool:
    m = re.match(r"t=(\d+),v1=([a-f0-9]+)", header or "")
    if not m or abs(time.time() - int(m.group(1))) > 300:
        return False
    atteso = hmac.new(secret.encode(), m.group(1).encode() + b"." + body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(atteso, m.group(2))

Impostarlo con l'API

curl https://app.mailsenpai.com/relay/v1/webhook \
  -H "Authorization: Bearer $SMTPSENPAI_CHIAVE" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://tuosito.it/webhook/mailsenpai", "eventi": ["delivered", "bounce", "complaint"]}'

Errori

Un errore ha sempre "ok": false e un campo errore con la spiegazione in italiano, insieme al codice HTTP:

{
  "ok": false,
  "errore": "volume del mese esaurito: aumenta il piano o accendi la continuità di invio dalla tua area",
  "residuo": 0,
  "aumenta": "https://app.mailsenpai.com/customer/il-mio-piano",
  "pannello": "https://app.mailsenpai.com/customer/relay-smtp"
}

Limiti

Modulo per i siti

Per i siti che non sanno mandare email (pagine statiche, temi senza plugin, hosting che bloccano la posta). Crea il modulo nell'area cliente, copia il suo indirizzo e mettilo nell'attributo action del tuo form, con method="POST". Non serve nessuna chiave.

<form action="https://app.mailsenpai.com/relay/f/CODICE" method="POST">
  <label>Nome <input type="text" name="nome" required></label>
  <label>Email <input type="email" name="email" required></label>
  <label>Messaggio <textarea name="messaggio" required></textarea></label>

  <input type="hidden" name="_subject" value="Nuova richiesta dal sito">
  <input type="hidden" name="_next" value="https://www.tuosito.it/grazie/">
  <input type="text" name="_gotcha" style="display:none" tabindex="-1" autocomplete="off">

  <button type="submit">Invia</button>
</form>

Sostituisci CODICE con il codice del tuo modulo. Ogni compilazione ti arriva per email, impaginata, con il Reply-To di chi ha scritto: premi rispondi e gli scrivi.

Campi speciali

Gli altri nomi che iniziano con _ vengono ignorati. I file allegati al form non vengono trasmessi.

Invio con JavaScript

Se mandi il form con fetch e l'intestazione Accept: application/json (oppure con un corpo JSON), la risposta è JSON e puoi restare sulla pagina. L'indirizzo accetta richieste da qualunque sito (CORS): per limitarlo ai tuoi, indica i domini nelle impostazioni del modulo.

const form = document.querySelector('form[action*="/relay/f/"]');

form.addEventListener('submit', async (event) => {
  event.preventDefault();
  const risposta = await fetch(form.action, {
    method: 'POST',
    body: new FormData(form),
    headers: { Accept: 'application/json' },
  });
  const esito = await risposta.json();
  if (esito.ok) {
    form.replaceWith('Grazie, ti rispondiamo presto.');
  } else {
    alert(esito.errore);
  }
});

Le email dei moduli partono da moduli@tuodominio.it, con il nome del modulo come mittente, e contano nel volume del mese come tutte le altre. Se vuoi, chi compila riceve una risposta automatica con le tue parole, e ogni compilazione resta archiviata nell'area cliente.

SMTP

Per i programmi che hanno già una schermata server SMTP (gestionali, e-commerce, CRM, WordPress) e quando servono allegati o più destinatari.

Cosa succede in SMTP

• Mittente (From) su un dominio non verificato: il messaggio viene rifiutato con 550 5.7.1.
• Destinatario nella lista di soppressione: il server risponde OK, così il tuo programma non va in errore, ma l'email non parte, non consuma volume e nel registro compare come dropped.
• Credenziali sbagliate: 535 5.7.8.
• Gli invii SMTP finiscono nello stesso registro e nelle stesse statistiche dell'API.

Buone pratiche

• Pubblica tutti i record DNS che trovi nell'area: la firma DKIM sul tuo dominio e l'SPF dicono ai provider che le email sono davvero tue. Aggiungi un record DMARC, partendo da p=none.
• Spedisci sempre da un indirizzo del dominio verificato e usa rispondi_a se le risposte devono arrivare altrove.
• Manda sempre anche la versione testuale, o lascia che la ricaviamo noi dall'HTML: le email solo immagine o solo HTML arrivano peggio.
• Lascia lavorare la soppressione: rimbalzi definitivi e segnalazioni di spam escono da soli dagli invii. Aggiungi tu chi chiede di non essere più contattato.
• Riprova solo sugli errori temporanei (502), con attesa crescente; mai su 400, 401 e 403.
• Usa le intestazioni X-… per collegare l'email al tuo sistema (numero d'ordine, id utente) e conserva id_messaggio.
• Controlla ogni tanto /statistiche: un tasso di rimbalzo che sale è il primo segnale di una lista da pulire.
• Tieni separate le email di servizio da quelle promozionali: per le campagne c'è la piattaforma MailSenpai.