HISEND DocsInbound Webhooks
React to incoming emails dynamically
HiSend goes beyond sending emails—it can also act as powerful, programmable receiving infrastructure. You can configure HiSend to listen to incoming emails on your verified domains and forward those payloads directly to your servers via Webhooks.
How It Works
When an email arrives at your verified domain (e.g. anything@example.com):
- HiSend Receives the Payload: The email is processed, parsed, and scrubbed of spam/malware at edge locations.
- Matching Endpoints: The system checks your project's routing rules to identify matching recipient addresses or catch-all patterns.
- Webhook Dispatch: HiSend issues an
HTTP POSTrequest to your designated Webhook URL containing a structured JSON payload of the parsed message.
Webhook Payload Structure
When your server receives a webhook request from HiSend, the POST body will contain a comprehensive JSON structure representing the email:
{
"id": 12345,
"project_id": 99,
"message_id": "<abcdef123456@mail.gmail.com>",
"direction": "inbound",
"status": "received",
"from": {
"name": "Jane Doe",
"email": "jane@example.com"
},
"to": [
{
"name": "Support Team",
"email": "support@yourverifieddomain.com"
}
],
"subject": "Help with my account",
"html_body": "<html><body><p>Can you help me reset my password?</p></body></html>",
"text_body": "Can you help me reset my password?",
"created_at": "2026-03-15T23:00:00Z"
}Responding to Webhooks
Your application must respond to the webhook trigger with a generic 200 OK or 202 Accepted HTTP status code. If your server returns an error or times out, HiSend will generally abort that delivery attempt and log a failure in your dashboard metrics.
Example: Express.js Webhook Receiver
Here is a simple example of receiving an inbound HiSend webhook using Node.js and Express:
import express from 'express';
const app = express();
app.use(express.json());
app.post('/api/webhooks/hisend', (req, res) => {
const emailPayload = req.body;
if (emailPayload.direction === 'inbound') {
console.log(`Received email from: ${emailPayload.from.email}`);
console.log(`Subject: ${emailPayload.subject}`);
// Process the email... (e.g., create a support ticket)
}
// Acknowledge receipt
res.status(200).send('OK');
});
app.listen(3000, () => console.log('Webhook server listening properly'));