L'API REST di Mailbeam vive su https://api.mailbeam.dev con tutti gli endpoint sotto /v1/. Le richieste si autenticano con un token Bearer, inviano e ricevono JSON, e restituiscono il risultato direttamente senza busta: gli errori sono le uniche risposte incartate, e portano un codice di errore, un messaggio e un request_id.

URL di base: https://api.mailbeam.dev/v1/
Intestazione di autenticazione: Authorization: Bearer mb_live_…
Tipo di contenuto: application/json
Campi di errore: error · message · request_id

Riferimento dell'API

L'API REST di Mailbeam ti permette di verificare indirizzi email, lanciare lavori in blocco e consultare il consumo del tuo account.

URL di base

https://api.mailbeam.dev

Tutti gli endpoint stanno sotto /v1/. I cambiamenti che rompono la compatibilità saranno introdotti in versioni nuove (/v2/, eccetera).

Autenticazione

Tutte le richieste hanno bisogno di un token Bearer nell'intestazione Authorization:

Authorization: Bearer mb_live_xxxxxxxxxxxxxxxxxxxx

In Autenticazione trovi i tipi di chiave, la rotazione e la modalità di prova.

Tipo di contenuto

Le richieste con un corpo devono inviare Content-Type: application/json. Tutte le risposte restituiscono Content-Type: application/json.

Versionamento

La versione attuale dell'API è v1. Manteniamo la compatibilità all'indietro dentro una versione. Quando sarà necessario romperla, pubblicheremo una versione nuova e segnaleremo la vecchia come deprecata con almeno 12 mesi di preavviso.

Idempotenza

L'endpoint POST /v1/verify si può ritentare senza problemi: non ha effetti collaterali. Chiamarlo due volte con la stessa email restituisce lo stesso risultato (a parte variazioni di tempo o di rete).

Per POST /v1/verify/batch, usa l'intestazione Idempotency-Key per ritentare gli invii senza creare lavori doppi:

Idempotency-Key: your-unique-job-id

Busta della risposta

Tutte le risposte corrette restituiscono il risultato direttamente, senza busta. Gli errori restituiscono:

{
  "error": "error_code",
  "message": "Human-readable description.",
  "request_id": "req_01hx9abc123"
}

Endpoint

Metodo	Percorso	Descrizione
`POST`	`/v1/verify`	Verificare un'email
`POST`	`/v1/verify/batch`	Inviare un lotto di email
`GET`	`/v1/jobs/:id`	Consultare lo stato di un lavoro in blocco
`GET`	`/v1/account/usage`	Consultare il consumo attuale della quota

Domande frequenti

Qual è l'URL di base dell'API di Mailbeam?

https://api.mailbeam.dev, con tutti gli endpoint sotto il prefisso /v1/. Le richieste con un corpo devono inviare Content-Type: application/json, e tutte le risposte restituiscono JSON.

Come si autenticano le richieste all'API di Mailbeam?

Con un token Bearer nell'intestazione Authorization, in questa forma: Authorization: Bearer mb_live_xxxxxxxxxxxxxxxxxxxx. Non c'è nessun altro schema di autenticazione, e le chiavi si ruotano dal pannello.

Che aspetto ha un errore dell'API di Mailbeam?

Le risposte corrette restituiscono il risultato direttamente, senza busta. Gli errori restituiscono un oggetto JSON con tre campi: error (un codice stabile e leggibile dalla macchina), message (una descrizione leggibile dalle persone) e request_id, che è quello che serve all'assistenza per rintracciare una chiamata precisa.

Quali endpoint di Mailbeam si possono ritentare senza rischi?

POST /v1/verify si può ritentare perché non ha effetti collaterali: lo stesso indirizzo restituisce lo stesso risultato. POST /v1/verify/batch crea un lavoro, quindi i ritentativi devono portare un'intestazione Idempotency-Key per non inviare due volte lo stesso lavoro.

Risposte verificate sul contratto dell'API il 2026-08-10.