E-mail API en webhooks
Naast SMTP heeft 2mail een REST API: u verstuurt een bericht met één HTTPS-aanroep, vraagt achteraf de status ervan op, en laat elke gebeurtenis — afgeleverd, gebounced, geopend — automatisch naar uw eigen systeem duwen via een webhook.
Deze pagina beschrijft wat de API doet en hoe de toegang werkt. De volledige referentie met alle velden en voorbeeldaanroepen zit in het klantenportaal, achter uw login.
Wat u ermee bouwt
Versturen vanuit uw toepassing
Eén POST met afzender, ontvanger, onderwerp en inhoud. U kunt een bericht ook vooruit plannen en per bericht bepalen of opens gemeten worden. Het antwoord bevat meteen een id waarmee u het bericht later terugvindt.
De status van één bericht opvragen
Met dat id vraagt u op of het bericht in de wachtrij staat, verzonden is of gefaald — inclusief de reden bij een fout. Zo hoeft u niet in logbestanden te zoeken wanneer een klant belt over één specifieke e-mail.
Gebeurtenissen automatisch ontvangen
Registreer een URL en 2mail duwt elke gebeurtenis erheen zodra ze zich voordoet: afgeleverd, uitgesteld, gebounced, geweigerd, geopend of mislukt. Geen polling, geen wachtrij die u zelf moet leeghalen.
Een sleutel per toepassing
Elke toepassing krijgt een eigen sleutel die u apart kunt intrekken. Een verzendsleutel mag uitsluitend versturen en de status van zijn eigen berichten opvragen — verder niets, ook geen andere gegevens van uw account.
Een bericht versturen
De aanroep is bewust klein gehouden: een sleutel in de Authorization-header en een JSON-body. Het afzenderadres moet op een van uw eigen domeinen staan.
POST https://www.2mail.eu/2mail/api/v1/messages Authorization: Bearer 2m_live_UW_SLEUTEL Content-Type: application/json { "from": "no-reply@uwdomein.be", "to": "klant@voorbeeld.be", "subject": "Uw bestelling is verzonden", "html": "<p>Bedankt voor uw bestelling.</p>" }
202 Accepted { "id": "4f3c…", "status": "queued" }
U krijgt een 202 terug met een id. Dat betekent aangenomen, niet afgeleverd — de aflevering zelf volgt u met een statusaanvraag of, beter, met een webhook.
Webhooks: de aflevering volgt u passief
Een webhook is een URL van uzelf die wij aanroepen zodra er iets met uw bericht gebeurt. Dat is nauwkeuriger dan periodiek de status opvragen, en u merkt een bounce binnen de minuut in plaats van bij de volgende ronde.
POST https://uwdomein.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": "klant@voorbeeld.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'] );
Elke aanroep is ondertekend
Wij sturen een handtekening mee in de header X-2mail-Signature, berekend met HMAC-SHA256 over de tijdstempel en de ruwe body, met een sleutel die alleen u en wij kennen. Controleer die handtekening voordat u de inhoud vertrouwt: zonder controle kan iedereen die uw URL kent gebeurtenissen verzinnen.
Mislukte aanroepen worden herhaald
Antwoordt uw endpoint niet met een 2xx, dan proberen we het opnieuw met oplopende tussenpozen — na een minuut, vijf minuten, een half uur, twee uur en zes uur. In het portaal ziet u per poging de responscode en de foutmelding, zodat u een falend endpoint kunt opsporen zonder ons te contacteren.
Welke gebeurtenissen
Afgeleverd, uitgesteld, gebounced, geweigerd, geopend, aangenomen en mislukt. U kiest per webhook welke types u wilt ontvangen, of laat het leeg voor alles.
Sleutels en toegang
Een API-sleutel wordt eenmalig getoond en daarna alleen als hash bewaard. Raakt u hem kwijt, dan trekt u hem in en maakt u een nieuwe — wij kunnen hem niet opnieuw tonen.
Verzendsleutel
Hoort bij één postbus en mag exact twee dingen: een bericht versturen en de status van zijn eigen berichten opvragen. Elk ander eindpunt antwoordt met 403. Dit is de sleutel die u in een webshop of applicatie zet.
Beheersleutel
Voor wie postbussen, domeinen en SMTP-gebruikers programmatisch wil aanmaken — bijvoorbeeld een partner die klanten in eigen beheer uitrolt. Deze sleutel maakt u aan in het portaal, niet via de API.
U maakt en beheert verzendsleutels zelf in het klantenportaal, onder Instellingen. Daar ziet u ook wanneer elke sleutel voor het laatst gebruikt is.
De volledige documentatie
Elk eindpunt, elk veld en elke foutcode staat in de interactieve referentie. Daar kunt u ook meteen uitproberen: klik op Authorize, plak uw sleutel en voer een echte aanroep uit.
De specificatie is openbaar en importeerbaar in Postman of Insomnia, of bruikbaar om een client te genereren. De interactieve referentie vraagt een login.
Aan de slag
De API zit bij elk 2mail-pakket inbegrepen; er is geen aparte licentie of module voor. Hebt u een vraag over een koppeling of wilt u weten of uw scenario past, laat het ons weten — we denken graag mee voor u begint te bouwen.
