API e-mail e webhook
Oltre all'SMTP, 2mail dispone di un'API REST: invii un messaggio con una sola chiamata HTTPS, ne consulti in seguito lo stato e fai inviare automaticamente ogni evento — recapitato, respinto, aperto — al tuo sistema tramite un webhook.
Questa pagina descrive che cosa fa l'API e come funziona l'accesso. Il riferimento completo con tutti i campi e le chiamate di esempio è pubblico: puoi consultarlo prima ancora di avere un account. Se lavori in PHP, l'SDK ufficiale si occupa per te del lavoro HTTP.
Che cosa costruisci con l'API
Inviare dalla tua applicazione
Una POST con mittente, destinatario, oggetto e contenuto. Puoi anche programmare un messaggio in anticipo e decidere per ogni messaggio se misurare le aperture. La risposta contiene subito un id con cui ritrovare il messaggio in seguito.
Consultare lo stato di un singolo messaggio
Con quell'id verifichi se il messaggio è in coda, è stato inviato o è fallito — motivo dell'errore incluso. Così non devi cercare nei file di log quando un cliente chiama per una specifica e-mail.
Ricevere automaticamente gli eventi
Registra un URL e 2mail vi invia ogni evento non appena si verifica: recapitato, differito, respinto, rifiutato, aperto o fallito. Nessun polling, nessuna coda da svuotare.
Una chiave per applicazione
Ogni applicazione riceve una chiave dedicata che puoi revocare separatamente. Una chiave di invio può esclusivamente inviare e consultare lo stato dei propri messaggi — nient'altro, nemmeno altri dati del tuo account.
Inviare un messaggio
La chiamata è volutamente essenziale: una chiave nell'header Authorization e un body JSON. L'indirizzo mittente deve appartenere a uno dei tuoi domini.
POST https://www.2mail.eu/2mail/api/v1/messages Authorization: Bearer 2m_live_UW_SLEUTEL Content-Type: application/json { "from": "no-reply@tuodominio.be", "to": "cliente@esempio.be", "subject": "Il tuo ordine è stato spedito", "html": "<p>Grazie per il tuo ordine.</p>" }
202 Accepted { "id": "4f3c…", "status": "queued" }
Ricevi un 202 con un id. Significa accettato, non recapitato — il recapito lo segui con una richiesta di stato o, meglio, con un webhook.
Preferisci non scrivere HTTP? L'SDK PHP
composer require jaanbv/2mail-php-api $api = new TwoMail($apiKey); $api->sendMail( 'no-reply@tuodominio.be', 'cliente@esempio.be', 'Il tuo ordine è stato spedito', '<p>Grazie per il tuo ordine.</p>' );
Per PHP esiste un client ufficiale che copre ogni endpoint qui sopra. La stessa chiamata diventa quattro righe e non devi occuparti tu di opzioni curl, codifica JSON o gestione degli errori.
L'SDK tiene distinti l'indirizzo mittente e il nome visualizzato, verifica per te le firme dei webhook e assegna a ogni codice di errore un'eccezione dedicata — così puoi reagire al tipo di errore invece che a un testo che domani potrebbe essere formulato diversamente.
Webhook: segui il recapito senza sforzo
Un webhook è un tuo URL che chiamiamo non appena succede qualcosa al tuo messaggio. È più preciso di una consultazione periodica dello stato e rilevi un bounce entro un minuto invece che al giro successivo.
POST https://tuodominio.be/webhooks/2mail X-2mail-Event: bounced X-2mail-Signature: t=1755417600,v1=<hmac-sha256> { "event": "bounced", "timestamp": "2026-08-17T10:04:11+02:00", "recipient": "cliente@esempio.be", "message_id": "<…>", "detail": "550 5.1.1 unknown", "code": "5.1.1" }
// $secret: eenmalig getoond bij aanmaak $body = file_get_contents('php://input'); parse_str(strtr($_SERVER['HTTP_X_2MAIL_SIGNATURE'], ',', '&'), $p); $ok = hash_equals( hash_hmac('sha256', $p['t'] . '.' . $body, $secret), $p['v1'] );
Ogni chiamata è firmata
Inviamo una firma nell'header X-2mail-Signature, calcolata con HMAC-SHA256 sul timestamp e sul body grezzo, con una chiave nota solo a te e a noi. Verifica quella firma prima di fidarti del contenuto: senza verifica, chiunque conosca il tuo URL può inventare eventi. In PHP non devi scriverlo tu: l'SDK effettua la verifica in una riga, compreso il controllo della finestra temporale che impedisce il riutilizzo di una chiamata intercettata.
Le chiamate fallite vengono ripetute
Se il tuo endpoint non risponde con un 2xx, riproviamo a intervalli crescenti — dopo un minuto, cinque minuti, mezz'ora, due ore e sei ore. Nel portale vedi per ogni tentativo il codice di risposta e il messaggio di errore, così puoi individuare un endpoint difettoso senza contattarci.
Quali eventi
Recapitato, differito, respinto, rifiutato, aperto, accettato e fallito. Scegli per ogni webhook quali tipi ricevere, oppure lascia vuoto per riceverli tutti.
Chiavi e accessi
Una chiave API viene mostrata una sola volta e in seguito conservata solo come hash. Se la perdi, la revochi e ne crei una nuova — non possiamo mostrartela di nuovo.
Chiave di invio
Appartiene a una sola casella e può fare esattamente due cose: inviare un messaggio e consultare lo stato dei propri messaggi. Ogni altro endpoint risponde con 403. È la chiave che inserisci in un e-commerce o in un'applicazione.
Chiave di amministrazione
Per chi vuole creare caselle, domini e utenti SMTP in modo programmatico — ad esempio un partner che gestisce i clienti in autonomia. Questa chiave la crei nel portale, non tramite l'API.
Crei e gestisci tu stesso le chiavi di invio nel portale clienti, sotto Impostazioni. Lì vedi anche quando ogni chiave è stata usata l'ultima volta.
La documentazione completa
Ogni endpoint, ogni campo e ogni codice di errore si trovano nel riferimento interattivo. Lì puoi anche fare subito una prova: clicca su Authorize, incolla la tua chiave ed esegui una chiamata reale.
La specifica è pubblica e importabile in Postman o Insomnia, oppure utilizzabile per generare un client. Anche il riferimento interattivo è liberamente accessibile — ti serve una chiave solo quando vuoi eseguire davvero una chiamata.
Iniziare
L'API è compresa in ogni pacchetto 2mail; non esiste una licenza o un modulo a parte. Hai una domanda su un'integrazione o vuoi sapere se il tuo scenario è compatibile? Faccelo sapere — ne parliamo volentieri prima che tu inizi a sviluppare.