{ "openapi": "3.1.0", "info": { "title": "SMTP Senpai API", "version": "1.0.0", "summary": "Transactional email sending, log, suppression list and website forms.", "description": "REST API of SMTP Senpai, the MailSenpai relay. Every response is JSON with an `ok` field; on errors there is also `errore`, with an Italian message. You find the key in the customer area, SMTP Senpai page. Call it from your server: the API does not accept browser requests (no CORS), except the form endpoint.", "contact": { "name": "MailSenpai", "url": "https://en.mailsenpai.com/smtp-api/" } }, "externalDocs": { "description": "Documentation with examples", "url": "https://en.mailsenpai.com/smtp-api/" }, "servers": [ { "url": "https://app.mailsenpai.com/relay/v1" } ], "security": [ { "chiaveBearer": [] } ], "tags": [ { "name": "Sending" }, { "name": "Account" }, { "name": "Log" }, { "name": "Suppression" }, { "name": "Website forms" } ], "paths": { "/stato": { "get": { "operationId": "stato", "tags": [ "Account" ], "summary": "SMTP credentials, monthly volume and account status", "description": "Does not return the SMTP password: you read and change it in the customer area.", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Stato" }, "example": { "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 } } } }, "401": { "$ref": "#/components/responses/ChiaveNonValida" }, "403": { "$ref": "#/components/responses/Sospeso" } } } }, "/invio": { "post": { "operationId": "invio", "tags": [ "Sending" ], "summary": "Send an email to one recipient", "description": "One call = one recipient. No attachments, CC or BCC: use SMTP for those. The sender must be on a verified domain. If the recipient is on the suppression list the response is 200 with `inviato: false` and the email is not sent. There is no idempotency key: after a 502 or a timeout check `/eventi` before retrying.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvioRichiesta" }, "examples": { "italiano": { "summary": "Italian field names", "value": { "a": "cliente@esempio.it", "da": "ordini@tuodominio.it", "nome_mittente": "Il tuo negozio", "oggetto": "Conferma ordine 10293", "html": "

Grazie, il tuo ordine è confermato.

", "rispondi_a": "assistenza@tuodominio.it", "intestazioni": { "X-Ordine": "10293" } } }, "inglese": { "summary": "English aliases", "value": { "to": "customer@example.com", "from": "orders@yourdomain.com", "from_name": "Your shop", "subject": "Order 10293 confirmed", "text": "Thanks, your order is confirmed." } } } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/InvioRichiesta" } } } }, "responses": { "200": { "description": "Accepted, or held because the recipient is suppressed.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/InvioOk" }, { "$ref": "#/components/schemas/InvioSoppresso" } ] }, "examples": { "inviata": { "value": { "ok": true, "inviato": true, "id_messaggio": "9f2c4e1a7b3d5f6e8a9b0c1d@tuodominio.it", "residuo": 8759, "oltre_il_piano": false } }, "soppressa": { "value": { "ok": true, "inviato": false, "motivo": "indirizzo nella lista di soppressione" } } } } } }, "400": { "description": "Missing or invalid data.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Errore" }, "example": { "ok": false, "errore": "destinatario non valido" } } } }, "401": { "$ref": "#/components/responses/ChiaveNonValida" }, "403": { "description": "Sender on an unverified domain, or account suspended.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Errore" }, "example": { "ok": false, "errore": "il dominio esempio.com non risulta fra quelli verificati per il tuo account" } } } }, "429": { "description": "Monthly volume used up and sending continuity off (or spending cap reached).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErroreVolume" }, "example": { "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" } } } }, "502": { "description": "The sending server did not accept the message or could not be reached: the text reports the reply received.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Errore" }, "example": { "ok": false, "errore": "il server di invio ha risposto: 451 4.3.0 errore temporaneo" } } } } } } }, "/statistiche": { "get": { "operationId": "statistiche", "tags": [ "Log" ], "summary": "Summary of the last days", "parameters": [ { "name": "giorni", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 90, "default": 30 }, "description": "Out-of-range values are clamped to 1-90." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "giorni": { "type": "integer" }, "dati": { "$ref": "#/components/schemas/Conteggi" }, "per_giorno": { "description": "Counts by date and type (at most the last 30 days). With no activity it is an empty array `[]`.", "oneOf": [ { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": { "type": "integer" } } }, { "type": "array", "maxItems": 0 } ] } } }, "example": { "ok": true, "giorni": 7, "dati": { "sent": 812, "delivered": 798, "bounce": 9, "defer": 14, "complaint": 0, "tracciamento": "not active", "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 } } } } } }, "401": { "$ref": "#/components/responses/ChiaveNonValida" }, "403": { "$ref": "#/components/responses/Sospeso" } } } }, "/eventi": { "get": { "operationId": "eventi", "tags": [ "Log" ], "summary": "Latest events, newest first", "description": "The detailed log covers the last 90 days. There is no pagination: at most 500 rows.", "parameters": [ { "name": "tipo", "in": "query", "schema": { "$ref": "#/components/schemas/TipoEvento" }, "description": "Filter by type. `open` and `click` require tracking (otherwise 403)." }, { "name": "quanti", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 50 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "eventi": { "type": "array", "items": { "$ref": "#/components/schemas/Evento" } } } }, "example": { "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" } ] } } } }, "401": { "$ref": "#/components/responses/ChiaveNonValida" }, "403": { "description": "You asked for opens or clicks without tracking, or the account is suspended.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Errore" }, "example": { "ok": false, "errore": "servizio sospeso: piano scaduto. Controlla il tuo piano nell'area cliente." } } } } } } }, "/soppressi": { "get": { "operationId": "soppressi", "tags": [ "Suppression" ], "summary": "Addresses and domains we no longer email", "parameters": [ { "name": "quanti", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 100 } }, { "name": "cerca", "in": "query", "schema": { "type": "string" }, "description": "Part of the address to search for." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "totale": { "type": "integer", "description": "Total entries on the list (ignores `cerca`)." }, "elenco": { "type": "array", "items": { "$ref": "#/components/schemas/Soppresso" } } } }, "example": { "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" } ] } } } }, "401": { "$ref": "#/components/responses/ChiaveNonValida" }, "403": { "$ref": "#/components/responses/Sospeso" } } } }, "/sopprimi": { "post": { "operationId": "sopprimi", "tags": [ "Suppression" ], "summary": "Add an address or a domain to the suppression list", "description": "For a whole domain write `@domain.com` or `domain.com`. Returns `ok: false` if the entry is invalid or already present.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string", "example": "mario@esempio.it" }, "nota": { "type": "string", "maxLength": 255 } } } }, "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string" }, "nota": { "type": "string" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Esito" }, "example": { "ok": true } } } }, "401": { "$ref": "#/components/responses/ChiaveNonValida" }, "403": { "$ref": "#/components/responses/Sospeso" } } } }, "/riammetti": { "post": { "operationId": "riammetti", "tags": [ "Suppression" ], "summary": "Remove from the list an entry you added yourself", "description": "Write the entry exactly as it appears on the list (domains with the at sign, `@domain.com`). Addresses that entered because of a bounce or a spam report should not be re-admitted from here: ask for a review in the customer area.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string", "example": "mario@esempio.it" } } } }, "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string" } } } } } }, "responses": { "200": { "description": "`ok: true` if the entry existed and was removed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Esito" }, "example": { "ok": true } } } }, "401": { "$ref": "#/components/responses/ChiaveNonValida" }, "403": { "$ref": "#/components/responses/Sospeso" } } } }, "/relay/f/{codice}": { "servers": [ { "url": "https://app.mailsenpai.com", "description": "Form endpoint host" } ], "parameters": [ { "name": "codice", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9]{6,32}$" }, "description": "The form code, copied from the customer area." } ], "get": { "operationId": "moduloInfo", "tags": [ "Website forms" ], "security": [], "summary": "Reminder of how to use the address", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModuloInfo" }, "example": { "ok": true, "modulo": "Contatti sito", "come": "Punta qui l'attributo action del tuo form, con method=\"POST\".", "campi": [ "_subject", "_replyto", "_next", "_cc", "_gotcha", "_format" ] } } } }, "404": { "description": "Form not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Errore" }, "example": { "ok": false, "errore": "modulo non trovato" } } } } } }, "post": { "operationId": "moduloInvia", "tags": [ "Website forms" ], "security": [], "summary": "Receives a submission from your website form", "description": "No key: the address is public by nature and is protected by restricting it to your domains (form setting). It answers in JSON if the request has `Accept: application/json`, `X-Requested-With: XMLHttpRequest` or a JSON body; otherwise, with a classic browser submission, it redirects with 303 to `_next` (or the page set in the form) or shows a confirmation page. Every delivered email counts towards the monthly volume.", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/ModuloCampi" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/ModuloCampi" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ModuloCampi" }, "example": { "nome": "Mario Rossi", "email": "mario@esempio.it", "messaggio": "Vorrei un preventivo", "_subject": "Richiesta dal sito", "_gotcha": "" } } } }, "responses": { "200": { "description": "Received (JSON), or HTML confirmation page for classic submissions without a thank-you page.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "messaggio": { "type": "string" } } }, "example": { "ok": true, "messaggio": "Grazie, il messaggio è arrivato." } }, "text/html": { "schema": { "type": "string" } } } }, "303": { "description": "Classic submission: redirect to the thank-you page.", "headers": { "Location": { "schema": { "type": "string", "format": "uri" } } } }, "400": { "description": "Classic submission failed: HTML page with the reason.", "content": { "text/html": { "schema": { "type": "string" } } } }, "403": { "description": "Form paused, service not active or website not allowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Errore" }, "example": { "ok": false, "errore": "questo modulo non è abilitato per www.altrosito.it" } } } }, "404": { "description": "Form not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Errore" }, "example": { "ok": false, "errore": "modulo non trovato" } } } }, "409": { "description": "No verified sending domain yet.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Errore" }, "example": { "ok": false, "errore": "il servizio non ha ancora un dominio di invio verificato" } } } }, "422": { "description": "No field filled in.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Errore" }, "example": { "ok": false, "errore": "il modulo è arrivato vuoto" } } } }, "429": { "description": "More than 25 submissions in an hour from the same network, or monthly volume used up.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Errore" }, "example": { "ok": false, "errore": "troppi invii ravvicinati: riprova fra qualche minuto" } } } }, "502": { "description": "Delivery failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Errore" }, "example": { "ok": false, "errore": "non siamo riusciti a consegnare la risposta: riprova" } } } } } }, "options": { "operationId": "moduloPreflight", "tags": [ "Website forms" ], "security": [], "summary": "CORS preflight for JavaScript submissions", "responses": { "204": { "description": "Allowed from any origin; POST and OPTIONS methods; Content-Type and Accept headers." } } } } }, "components": { "securitySchemes": { "chiaveBearer": { "type": "http", "scheme": "bearer", "bearerFormat": "msp_…", "description": "`Authorization: Bearer msp_…` (the key starts with `msp_` and is 52 characters long). As an alternative the `chiave` field is accepted in the body (JSON or form) and, for GET, as a URL parameter (discouraged: it ends up in logs)." } }, "schemas": { "Errore": { "type": "object", "required": [ "ok", "errore" ], "properties": { "ok": { "type": "boolean", "const": false }, "errore": { "type": "string", "description": "Human-readable explanation, always in Italian." } } }, "ErroreVolume": { "allOf": [ { "$ref": "#/components/schemas/Errore" }, { "type": "object", "properties": { "residuo": { "type": "integer", "const": 0 }, "aumenta": { "type": "string", "format": "uri", "description": "Customer-area page where you can raise the volume." }, "pannello": { "type": "string", "format": "uri", "description": "Customer-area page with usage and sending continuity." } } } ] }, "Stato": { "type": "object", "required": [ "ok", "stato", "smtp", "volume", "tracciamento", "soppressi" ], "properties": { "ok": { "type": "boolean", "const": true }, "stato": { "type": "string", "enum": [ "pending", "active" ], "description": "`pending` = account created, being activated; `active` = live. A suspended account never gets here: it receives 403." }, "smtp": { "type": "object", "properties": { "server": { "type": "string", "example": "relay.mailsenpai.com" }, "porta": { "type": "integer", "example": 2525 }, "porta_alternativa": { "type": "integer", "example": 2525 }, "utente": { "type": "string", "example": "r1234@tuodominio.it" }, "sicurezza": { "type": "string", "const": "STARTTLS" } } }, "volume": { "type": "object", "properties": { "mese": { "type": "string", "pattern": "^\\d{4}-\\d{2}$", "example": "2026-10" }, "incluso": { "type": "integer", "description": "Emails included in the month." }, "usato": { "type": "integer", "description": "Emails already counted this month (delivered or bounced)." }, "residuo": { "type": "integer" }, "per_ora": { "type": "integer", "description": "Hourly pace of the plan: above it messages wait in the queue, they are not rejected." } } }, "tracciamento": { "type": "boolean", "description": "True if open and click tracking is active." }, "soppressi": { "type": "integer", "description": "Entries on the suppression list." } } }, "InvioRichiesta": { "type": "object", "description": "One recipient per call. Italian names take precedence over the English aliases if you send both.", "properties": { "a": { "type": "string", "format": "email", "description": "Recipient (exactly one)." }, "to": { "type": "string", "format": "email", "description": "Alias of `a`." }, "da": { "type": "string", "format": "email", "description": "Sender: must be on a verified domain of your account (subdomains are accepted)." }, "from": { "type": "string", "format": "email", "description": "Alias of `da`." }, "nome_mittente": { "type": "string", "description": "Sender display name." }, "from_name": { "type": "string", "description": "Alias of `nome_mittente`." }, "oggetto": { "type": "string", "minLength": 1 }, "subject": { "type": "string", "description": "Alias of `oggetto`." }, "html": { "type": "string", "description": "HTML body. If the text part is missing, it is derived from the HTML." }, "testo": { "type": "string", "description": "Plain-text body." }, "text": { "type": "string", "description": "Alias of `testo`." }, "rispondi_a": { "type": "string", "format": "email", "description": "Reply-To address. Ignored if it is not a valid address." }, "reply_to": { "type": "string", "format": "email", "description": "Alias of `rispondi_a`." }, "intestazioni": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Custom headers. Only `X-…` names pass (letters, digits and hyphens, max 40 characters after `X-`); others are dropped silently.", "example": { "X-Ordine": "A-10293" } }, "headers": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Alias of `intestazioni`." } }, "allOf": [ { "anyOf": [ { "required": [ "a" ] }, { "required": [ "to" ] } ] }, { "anyOf": [ { "required": [ "da" ] }, { "required": [ "from" ] } ] }, { "anyOf": [ { "required": [ "oggetto" ] }, { "required": [ "subject" ] } ] }, { "anyOf": [ { "required": [ "html" ] }, { "required": [ "testo" ] }, { "required": [ "text" ] } ] } ] }, "InvioOk": { "type": "object", "required": [ "ok", "inviato", "id_messaggio" ], "properties": { "ok": { "type": "boolean", "const": true }, "inviato": { "type": "boolean", "const": true }, "id_messaggio": { "type": "string", "description": "Identifier given to the message; it is also its Message-ID (without angle brackets).", "example": "9f2c4e1a7b3d5f6e8a9b0c1d@tuodominio.it" }, "residuo": { "type": "integer", "description": "Estimate of the volume left this month." }, "oltre_il_piano": { "type": "boolean", "description": "True if the included volume was used up and the email went out thanks to sending continuity." } } }, "InvioSoppresso": { "type": "object", "required": [ "ok", "inviato", "motivo" ], "properties": { "ok": { "type": "boolean", "const": true }, "inviato": { "type": "boolean", "const": false }, "motivo": { "type": "string", "example": "indirizzo nella lista di soppressione" } } }, "Conteggi": { "type": "object", "properties": { "sent": { "type": "integer" }, "delivered": { "type": "integer" }, "bounce": { "type": "integer" }, "defer": { "type": "integer" }, "complaint": { "type": "integer" }, "open": { "type": "integer", "description": "Only with tracking active (unique recipients)." }, "click": { "type": "integer", "description": "Only with tracking active (unique recipients)." }, "tracciamento": { "type": "string", "description": "Present instead of open/click when tracking is not active." }, "tasso_consegna": { "type": "number", "description": "Percentage, one decimal place." }, "tasso_rimbalzo": { "type": "number" }, "tasso_segnalazioni": { "type": "number" } } }, "Evento": { "type": "object", "description": "Log row. Numbers are returned as strings; dates are UTC in `YYYY-MM-DD HH:MM:SS` format.", "properties": { "event_id": { "type": "string", "pattern": "^\\d+$" }, "relay_id": { "type": "string", "pattern": "^\\d+$" }, "type": { "$ref": "#/components/schemas/TipoEvento" }, "email": { "type": "string", "description": "Recipient." }, "domain": { "type": "string", "description": "Recipient domain." }, "from_domain": { "type": "string" }, "code": { "type": "string", "description": "Code returned by the recipient server, if any." }, "reason": { "type": "string", "description": "Readable reason (bounces, deferrals, drops)." }, "message_id": { "type": "string" }, "url": { "type": "string", "description": "Clicked link (click events only)." }, "happened_at": { "type": "string", "example": "2026-10-01 08:42:10" } } }, "TipoEvento": { "type": "string", "enum": [ "sent", "delivered", "bounce", "defer", "complaint", "open", "click", "dropped" ], "description": "`sent` accepted via API or form · `delivered` delivered · `bounce` permanent rejection · `defer` deferred, will retry · `complaint` spam report · `open`/`click` with tracking · `dropped` not sent because the recipient is on the suppression list." }, "Soppresso": { "type": "object", "properties": { "supp_id": { "type": "string", "pattern": "^\\d+$" }, "relay_id": { "type": "string", "pattern": "^\\d+$" }, "email": { "type": "string", "description": "Address, or a whole domain written `@domain.com`." }, "reason": { "type": "string", "enum": [ "bounce", "complaint", "manuale" ] }, "note": { "type": "string" }, "created_at": { "type": "string", "example": "2026-09-30 14:03:51" } } }, "Esito": { "type": "object", "required": [ "ok" ], "properties": { "ok": { "type": "boolean" } } }, "ModuloInfo": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "modulo": { "type": "string" }, "come": { "type": "string" }, "campi": { "type": "array", "items": { "type": "string" } } } }, "ModuloCampi": { "type": "object", "description": "All the fields of your form (max 60, max 5,000 characters each). Names starting with `_` are reserved: only the listed ones are used, others are ignored. File uploads are not supported.", "additionalProperties": { "type": "string" }, "properties": { "_subject": { "type": "string", "description": "Subject of the email you receive." }, "_replyto": { "type": "string", "format": "email", "description": "Reply address. If missing, the first field with «mail» in its name and a valid address is used." }, "_next": { "type": "string", "format": "uri", "description": "Thank-you page (full http/https address) for classic submissions." }, "_cc": { "type": "string", "format": "email", "description": "Copy to another address, only if allowed in the form settings." }, "_gotcha": { "type": "string", "description": "Honeypot field to keep empty and hidden: if filled, the submission is silently discarded." }, "_format": { "type": "string", "enum": [ "plain" ], "description": "`plain` to receive the email as plain text." } } } }, "responses": { "ChiaveNonValida": { "description": "Missing or invalid key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Errore" }, "example": { "ok": false, "errore": "chiave non valida" } } } }, "Sospeso": { "description": "Account suspended (plan expired or unpaid, volume used up without continuity, spending cap reached…). The message states the reason.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Errore" }, "example": { "ok": false, "errore": "servizio sospeso: volume del mese esaurito. Controlla il tuo piano nell'area cliente." } } } } } } }