SMTP Senpai API and SMTP

Three ways to send

They all lead to the same servers, with the same DKIM signature on your domain, the same log and the same suppression list. Pick the one that fits what you already have.

Before sending you need a verified domain: the customer area shows the DNS records to publish (they sign your emails with DKIM on your domain) and we check them. The sender of every email must be on that domain or one of its subdomains.

Authentication

Every API call carries your key in the header Authorization: Bearer msp_…. The key starts with msp_ and is 52 characters long: you find it in the customer area, SMTP Senpai page, «Key for your applications» box.

Authorization: Bearer msp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

• If you regenerate it in the customer area, the old one stops working immediately.
• Keep it on the server, in an environment variable: the API does not accept browser calls (it sends no CORS headers), so the key never ends up in a web page. For website forms use theform endpoint, which needs no key.
• If your platform cannot set custom headers, you can pass the key in the chiave field of the body (JSON or form). For GET requests it is also accepted as a URL parameter, but this is discouraged: URLs end up in server and proxy logs.
• SMTP credentials (username and password) are separate from the API key and are changed separately.

Missing or wrong key:

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

Your first send in one minute

1. Verify the domain you will send from (customer area, Domains page). If you have just started the trial, it is the domain you entered when signing up.
2. Copy the key and put it in an environment variable: export SMTPSENPAI_KEY=msp_…
3. Run this request, with a recipient of yours and a sender on the verified domain:

curl https://app.mailsenpai.com/relay/v1/invio \
  -H "Authorization: Bearer $SMTPSENPAI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "customer@example.com",
    "from": "orders@yourdomain.com",
    "subject": "Test from SMTP Senpai",
    "text": "It works!"
  }'

If everything is in place you get this response, and within seconds the email is in the inbox:

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

Keep id_messaggio: it is also the email's Message-ID and helps you find it in the log.

Ready-made examples: Node, Python, PHP

For each language there is a REST API version and an SMTP version. The examples read key, username and password from environment variables: SMTPSENPAI_KEY, SMTPSENPAI_USER, SMTPSENPAI_PASSWORD.

// Node.js 18+: fetch is built in
async function sendEmail() {
  const response = await fetch('https://app.mailsenpai.com/relay/v1/invio', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.SMTPSENPAI_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      to: 'customer@example.com',
      from: 'orders@yourdomain.com',
      from_name: 'Your shop',
      subject: 'Order 10293 confirmed',
      html: '<p>Thanks, your order is confirmed.</p>',
      reply_to: 'support@yourdomain.com',
    }),
  });
  const result = await response.json();
  if (!result.ok) {
    throw new Error(`${response.status}: ${result.errore}`);
  }
  console.log(result.inviato ? `Sent: ${result.id_messaggio}` : `Not sent: ${result.motivo}`);
}

sendEmail().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,      // start in plain text...
  requireTLS: true,   // ...and upgrade to STARTTLS right away
  auth: {
    user: process.env.SMTPSENPAI_USER,
    pass: process.env.SMTPSENPAI_PASSWORD,
  },
});

async function sendEmail() {
  const info = await transporter.sendMail({
    from: '"Your shop" <orders@yourdomain.com>',
    to: 'customer@example.com',
    subject: 'Your invoice',
    text: 'Please find your invoice attached.',
    html: '<p>Please find your invoice attached.</p>',
    attachments: [{ filename: 'invoice.pdf', path: './invoice.pdf' }],
  });
  console.log('Accepted:', info.messageId);
}

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

# pip install requests
import os
import requests

response = requests.post(
    "https://app.mailsenpai.com/relay/v1/invio",
    headers={"Authorization": f"Bearer {os.environ['SMTPSENPAI_KEY']}"},
    json={
        "to": "customer@example.com",
        "from": "orders@yourdomain.com",
        "from_name": "Your shop",
        "subject": "Order 10293 confirmed",
        "html": "<p>Thanks, your order is confirmed.</p>",
        "text": "Thanks, your order is confirmed.",
    },
    timeout=30,
)
result = response.json()
if not result["ok"]:
    raise RuntimeError(f"{response.status_code}: {result['errore']}")
print(result["id_messaggio"] if result["inviato"] else result["motivo"])

import os
import smtplib
from email.message import EmailMessage

msg = EmailMessage()
msg["From"] = "Your shop <orders@yourdomain.com>"
msg["To"] = "customer@example.com"
msg["Subject"] = "Your invoice"
msg.set_content("Please find your invoice attached.")
msg.add_alternative("<p>Please find your invoice attached.</p>", subtype="html")
with open("invoice.pdf", "rb") as attachment:
    msg.add_attachment(attachment.read(), maintype="application",
                       subtype="pdf", filename="invoice.pdf")

with smtplib.SMTP("relay.mailsenpai.com", 2525, timeout=30) as server:
    server.starttls()
    server.login(os.environ["SMTPSENPAI_USER"], 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_KEY'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS     => json_encode([
        'to' => 'customer@example.com',
        'from' => 'orders@yourdomain.com',
        'from_name' => 'Your shop',
        'subject' => 'Order 10293 confirmed',
        'html' => '<p>Thanks, your order is confirmed.</p>',
    ], JSON_UNESCAPED_UNICODE),
]);
$body   = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

$result = json_decode((string) $body, true);
if (empty($result['ok'])) {
    throw new RuntimeException($status . ': ' . ($result['errore'] ?? 'invalid response'));
}
echo $result['inviato'] ? $result['id_messaggio'] : $result['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_USER');
$mail->Password   = getenv('SMTPSENPAI_PASSWORD');
$mail->CharSet    = 'UTF-8';

$mail->setFrom('orders@yourdomain.com', 'Your shop');
$mail->addAddress('customer@example.com');
$mail->Subject = 'Your invoice';
$mail->isHTML(true);
$mail->Body    = '<p>Please find your invoice attached.</p>';
$mail->AltBody = 'Please find your invoice attached.';
$mail->addAttachment('invoice.pdf');
$mail->send();

In the customer area, «Ready-made examples» box, you also find the WordPress setup (WP Mail SMTP or FluentSMTP) already filled in with your details.

Endpoint reference

Base URL https://app.mailsenpai.com/relay/v1. Every response is JSON with an ok field. Responses use Italian field names and Italian error messages; /invio also accepts English field names.

curl https://app.mailsenpai.com/relay/v1/invio \
  -H "Authorization: Bearer $SMTPSENPAI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "customer@example.com",
    "from": "orders@yourdomain.com",
    "subject": "Test from SMTP Senpai",
    "text": "It works!"
  }'

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

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

{
  "ok": true,
  "stato": "active",
  "smtp": {
    "server": "relay.mailsenpai.com",
    "porta": 2525,
    "porta_alternativa": 2525,
    "utente": "r1234@yourdomain.com",
    "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_KEY"

{
  "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_KEY"

{
  "ok": true,
  "eventi": [
    {
      "event_id": "88213",
      "relay_id": "12",
      "type": "bounce",
      "email": "john@example.com",
      "domain": "example.com",
      "from_domain": "yourdomain.com",
      "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/soppressi?cerca=example.com" \
  -H "Authorization: Bearer $SMTPSENPAI_KEY"

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

curl https://app.mailsenpai.com/relay/v1/sopprimi \
  -H "Authorization: Bearer $SMTPSENPAI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "john@example.com", "nota": "asked not to be contacted"}'

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

Errors

An error always has "ok": false and an errore field with the explanation in Italian, together with the HTTP status:

{
  "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"
}

Limits

Website forms

For websites that cannot send email (static pages, themes without plugins, hosting that blocks mail). Create the form in the customer area, copy its address and put it in the action attribute of your form, with method="POST". No key needed.

<form action="https://app.mailsenpai.com/relay/f/CODICE" method="POST">
  <label>Name <input type="text" name="name" required></label>
  <label>Email <input type="email" name="email" required></label>
  <label>Message <textarea name="message" required></textarea></label>

  <input type="hidden" name="_subject" value="New enquiry from the website">
  <input type="hidden" name="_next" value="https://www.yoursite.com/thank-you/">
  <input type="text" name="_gotcha" style="display:none" tabindex="-1" autocomplete="off">

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

Replace CODICE with your form's code. Every submission reaches you by email, laid out, with the Reply-To of the person who wrote: hit «reply» and you write back.

Special fields

Other names starting with _ are ignored. Files attached to the form are not forwarded.

Submitting with JavaScript

If you submit the form with fetch and the header Accept: application/json (or a JSON body), the response is JSON and you can stay on the page. The address accepts requests from any website (CORS): to restrict it to yours, list your domains in the form settings.

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

form.addEventListener('submit', async (event) => {
  event.preventDefault();
  const response = await fetch(form.action, {
    method: 'POST',
    body: new FormData(form),
    headers: { Accept: 'application/json' },
  });
  const result = await response.json();
  if (result.ok) {
    form.replaceWith('Thanks, we will get back to you soon.');
  } else {
    alert(result.errore);
  }
});

Form emails are sent from moduli@yourdomain.com, with the form name as sender, and count towards the monthly volume like all the others. Optionally, whoever fills in the form gets an automatic reply in your words, and every submission is archived in the customer area.

SMTP

For programs that already have an «SMTP server» screen (ERPs, e-commerce, CRMs, WordPress) and when you need attachments or multiple recipients.

What happens over SMTP

• Sender (From) on an unverified domain: the message is rejected with 550 5.7.1.
• Recipient on the suppression list: the server answers OK, so your program does not error, but the email is not sent, uses no volume and shows in the log as dropped.
• Wrong credentials: 535 5.7.8.
• SMTP sends end up in the same log and statistics as the API.

Best practices

• Publish all the DNS records shown in your area: the DKIM signature on your domain and SPF tell providers the emails are really yours. Add a DMARC record, starting with p=none.
• Always send from an address on the verified domain and use reply_to if replies must go elsewhere.
• Always include a text version, or let us derive it from the HTML: image-only or HTML-only emails perform worse.
• Let suppression do its job: hard bounces and spam reports are removed from sending automatically. Add yourself anyone who asks not to be contacted.
• Retry only on temporary errors (502), with increasing waits; never on 400, 401 and 403.
• Use X-… headers to link the email to your system (order number, user id) and store id_messaggio.
• Check /statistiche now and then: a rising bounce rate is the first sign of a list that needs cleaning.
• Keep service emails separate from promotional ones: for campaigns there is the MailSenpai platform.