Email API and webhooks
Alongside SMTP, 2mail has a REST API: you send a message with a single HTTPS call, look up its status afterwards, and let every event — delivered, bounced, opened — be pushed to your own system through a webhook.
This page describes what the API does and how access works. The full reference, with every field and example calls, lives in the customer portal behind your login.
What you build with it
Send from your application
One POST with sender, recipient, subject and content. You can also schedule a message ahead and decide per message whether opens are tracked. The response carries an id straight away so you can find the message later.
Look up one message's status
With that id you can tell whether the message is queued, sent or failed — including the reason on failure. No digging through log files when a customer calls about one specific email.
Receive events automatically
Register a URL and 2mail pushes every event to it the moment it happens: delivered, deferred, bounced, rejected, opened or failed. No polling, no queue for you to drain.
A key per application
Every application gets its own key, revocable on its own. A send key may only send and look up the status of its own messages — nothing else, not even other data from your account.
Sending a message
The call is deliberately small: a key in the Authorization header and a JSON body. The sender address must belong to one of your own domains.
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" }
You get a 202 back with an id. That means accepted, not delivered — you follow the delivery itself with a status request or, better, with a webhook.
Webhooks: following delivery without asking
A webhook is a URL of your own that we call as soon as something happens to your message. That is more precise than polling for status, and you notice a bounce within the minute rather than on the next round.
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'] );
Every call is signed
We send a signature in the X-2mail-Signature header, computed as HMAC-SHA256 over the timestamp and the raw body, with a key only you and we know. Verify that signature before trusting the content: without the check, anyone who knows your URL can invent events.
Failed calls are retried
If your endpoint does not answer with a 2xx, we retry at increasing intervals — after a minute, five minutes, half an hour, two hours and six hours. The portal shows the response code and error message per attempt, so you can track down a failing endpoint without contacting us.
Which events
Delivered, deferred, bounced, rejected, opened, accepted and failed. You choose per webhook which types to receive, or leave it empty for all of them.
Keys and access
An API key is shown once and then stored only as a hash. If you lose it, you revoke it and create a new one — we cannot show it again.
Send key
Belongs to one mailbox and may do exactly two things: send a message and look up the status of its own messages. Every other endpoint answers 403. This is the key you put in a webshop or application.
Admin key
For anyone who wants to create mailboxes, domains and SMTP users programmatically — a partner rolling out their own customers, for instance. You create this key in the portal, not through the API.
You create and manage send keys yourself in the customer portal, under Settings. It also shows when each key was last used.
The full documentation
Every endpoint, every field and every error code is in the interactive reference. You can try it there directly too: click Authorize, paste your key and make a real call.
The specification is public and can be imported into Postman or Insomnia, or used to generate a client. The interactive reference requires a login.
Getting started
The API is included with every 2mail plan; there is no separate licence or module. Have a question about an integration, or want to know whether your scenario fits? Let us know — we are happy to think it through with you before you start building.
