Webhooks
Webhooks push message events to your server in real time, so you can update your own records without polling: log a delivery, flag a bounce, react to a spam complaint.
Add an endpoint
Open Webhooks → Add endpoint and enter an HTTPS URL that can receive POST requests. Mailhuset sends each event there as JSON.
When you add an endpoint you can subscribe to specific events, or leave the list blank to receive all of them.
Events
An event fires as a message moves through its lifecycle:
| Event | Meaning |
|---|---|
email.sent | Handed off to the receiving server |
email.delivered | The receiving server accepted the message |
email.bounced | Delivery failed (hard bounce = permanent, auto-suppressed) |
email.complained | The recipient marked it as spam (auto-suppressed) |
email.opened | The recipient opened it (open tracking on) |
email.clicked | The recipient clicked a link (click tracking on) |
email.rejected | The provider rejected the message before sending |
Each payload identifies the message (messageId), the provider message id, the event type, and an occurredAt timestamp, so you can correlate it with the send. The event type is also sent in the X-Mailhuset-Event header.
Respond quickly and verify
- Return a
2xxpromptly; do heavy work asynchronously. Mailhuset retries
failed deliveries with backoff, so your handler must be idempotent (the same event may arrive more than once).
- Verify events are genuinely from Mailhuset (check the signing secret shown when
you create the endpoint) before acting on them.
Bounces & complaints are handled for you
You don't have to suppress bad addresses yourself. Hard bounces and complaints are added to your suppression list automatically. Use the webhook to mirror that state in your own database.
Testing, delivery log & replay
Every delivery attempt is recorded. On the Webhooks page, open Deliveries under an endpoint to see recent attempts with their status, the HTTP code your server returned, the number of attempts, and the exact payload and response body.
- Send test event posts a realistic sample event to your endpoint straight
away and shows the result, so you can wire up and verify your handler before any real email flows.
- Replay re-sends a past event's payload as a fresh delivery — handy after you
fix a bug in your handler, or when your server was down.
- Disable pauses delivery to an endpoint without deleting it (and its history);
Enable turns it back on.
You can also point an endpoint at a request-inspection tool while developing, send yourself a real email, and watch the events arrive.
Sandbox mode
Sends made with a test API key (mh_test_…) or from a sandbox project are fully simulated: they're recorded in your message log but never actually sent, so they don't hit real inboxes, count against your quota, or bill. Use them to build and test your integration end to end. See API keys for test keys.
Need help? Email support@mailhuset.com.