Webhooks are the advanced temp mail API feature — get notified when emails arrive instead of polling. This guide shows you how to configure YYDS Mail Webhooks for automation.
What Is a Webhook
A webhook is a "reverse API": instead of you polling for data, the service POSTs to your URL when an event happens.
For temp mail: when an email arrives, the server notifies you automatically — no need to repeatedly call the API.
Webhook vs Polling
| Method | How | Pros | Cons | |--------|-----|------|------| | Polling | Query API every N seconds | Simple | Wastes quota, high latency | | Webhook | Server POSTs on event | Real-time, saves quota | Needs public endpoint |
For real-time needs (like verification code extraction), Webhook is better.
Configuration
Step 1: Prepare Your Endpoint
const express = require("express");
const app = express();
app.use(express.json());
app.post("/webhooks/mail", (req, res) => {
const event = req.body;
if (event.type === "message.received") {
const message = event.data;
console.log("Received:", message.subject);
// Process email...
}
res.json({ ok: true });
});
app.listen(3000);
Step 2: Register the Webhook
curl https://maliapi.215.im/v1/webhooks \
-X POST \
-H "X-API-Key: AC-your-key-here" \
-H "Content-Type: application/json" \
-d '{"url": "https://your-server.com/webhooks/mail", "events": ["message.received"]}'
Step 3: Verify and Test
YYDS Mail sends a verification request. Once confirmed, the webhook activates. Every new email triggers a POST to your URL.
Message Format
{
"type": "message.received",
"data": {
"id": "msg_xxx",
"from": "noreply@example.com",
"subject": "Your verification code",
"text": "Code is 123456",
"receivedAt": "2026-07-15T10:00:00Z"
}
}
Practical Scenarios
Auto-Extract Verification Codes
app.post("/webhooks/mail", (req, res) => {
const { text } = req.body.data;
const codeMatch = text.match(/code[:\s]*(\d{4,6})/i);
if (codeMatch) {
saveCode(req.body.data.accountId, codeMatch[1]);
}
res.json({ ok: true });
});
Trigger Automations
Receive emails from specific senders and trigger workflows (Slack notifications, database updates).
Security Tips
- Verify signatures: YYDS Mail signs requests — verify to confirm authenticity
- HTTPS required: webhook URLs must be HTTPS
- Respond fast: return 200 quickly, process in background
- Retry handling: non-200 responses trigger automatic retries
FAQ
Is webhook free? Included in API quota, no extra charge. See pricing.
Can webhooks lose messages? If your server is down, YYDS Mail retries. Implement polling as fallback.
Can I have multiple webhook URLs? Yes, configure different URLs for different events.
Want webhook automation? See full API docs, or read temp mail API getting started.