Receive email events via webhooks

Sidemail uses webhooks to notify your application when an event happens in your project. Webhooks are particularly useful for asynchronous events like when an email is delivered, bounces, is opened, when the recipient reports a spam complaint, or when your inbound route receives a new email.

How to set up

• In your project's API section, add a webhook URL, and get your unique webhook secret.
• In your webhook handler, compare the value of sidemail-secret header with your webhook secret to verify the request.
• Respond to the webhook request with 200 status code (response with any other status is recognized as a webhook failure).

Node.js webhook handler example:

function handleSidemailWebhook(req, res, next) {
	// Get your webhook secret in your project's API section
	const WEBHOOK_SECRET = "replace-with-your-webhook-secret";

	// Verify that the request is coming from Sidemail
	if (req.headers["sidemail-secret"] !== WEBHOOK_SECRET) {
		return res.status(401).send();
	}

	// Your custom logic ...
	console.log(req.body.type, req.body.data);

	// Acknowledge the webhook by responding with 200 status code
	return res.status(200).send();
}

Events

Event: email.delivered

{
	"type": "email.delivered",
	"data": {
		"email": {
			"id": "123",
			"templateId": "123",
			"templateName": "Welcome",
			"templateProps": { "name": "John" },
			"fromName": "Example App",
			"fromAddress": "[email protected]",
			"toAddress": "[email protected]",
			"createdAt": "2020-11-07T09:50:09.951Z"
		},
		"time": "2020-11-07T09:50:09.951Z",
		"smtpResponse": "250 2.6.0 Message received"
	}
}

Event: email.open

Triggered on the first open of an email by the recipient. Subsequent opens are not reported.

{
	"type": "email.open",
	"data": {
		"email": {
			"id": "123",
			"templateId": "123",
			"templateName": "Welcome",
			"templateProps": { "name": "John" },
			"fromName": "Example App",
			"fromAddress": "[email protected]",
			"toAddress": "[email protected]",
			"createdAt": "2020-11-07T09:50:09.951Z"
		},
		"time": "2020-11-07T09:50:09.951Z",
		"ipAddress": "203.0.113.10",
		"userAgent": "Mozilla/5.0 ..."
	}
}

Event: email.bounce

{
	"type": "email.bounce",
	"data": {
		"email": {
			"id": "123",
			"templateId": "123",
			"templateName": "Welcome",
			"templateProps": { "name": "John" },
			"fromName": "Example App",
			"fromAddress": "[email protected]",
			"toAddress": "[email protected]",
			"createdAt": "2020-11-07T09:50:09.951Z"
		},
		"time": "2020-11-07T09:50:09.951Z",
		"bounceType": "permanent"
	}
}

Event: email.complaint

{
	"type": "email.complaint",
	"data": {
		"email": {
			"id": "123",
			"templateId": "123",
			"templateName": "Welcome",
			"templateProps": { "name": "John" },
			"fromName": "Example App",
			"fromAddress": "[email protected]",
			"toAddress": "[email protected]",
			"createdAt": "2020-11-07T09:50:09.951Z"
		},
		"time": "2020-11-07T09:50:09.951Z",
		"complaintFeedbackType": "abuse"
	}
}

Event: email.received

Triggered when an inbound route receives an email.

{
	"type": "email.received",
	"data": {
		"email": {
			"id": "email_123456",
			"self": "https://api.sidemail.io/v1/inbound/emails/email_123456",
			"destination": "[email protected]",
			"from": { "email": "[email protected]", "name": "Sender" },
			"to": [{ "email": "[email protected]", "name": "Support Team" }],
			"cc": [{ "email": "[email protected]", "name": null }],
			"replyTo": [{ "email": "[email protected]", "name": "Billing" }],
			"subject": "Example inbound message",
			"text": "Hello, please find invoice attached...",
			"htmlAvailable": true,
			"attachments": [
				{ "name": "attachment.pdf", "contentType": "application/pdf", "size": 84320 }
			],
			"previewHtmlUrl": "https://api.sidemail.io/v1/inbound/emails/preview-html?token=...",
			"rawEmailUrl": "https://storage.example.com/..."
		},
		"spam": {
			"score": 2.4,
			"threshold": 15,
			"isSpam": false,
			"action": "accept",
			"symbols": ["R_SPF_ALLOW", "R_DKIM_ALLOW", "MIME_GOOD"]
		},
		"time": "2026-03-27T12:01:18.921Z"
	}
}

Notes:

• spam.symbols contains the rule names that contributed to spam scoring.
• email.self is a stable API URL for fetching full inbound email detail.
• destination is the SMTP recipient routed in Sidemail. Header recipients are in to and cc.
• previewHtmlUrl is present only when an HTML part is available and is short-lived (currently 15 minutes).
• rawEmailUrl is a short-lived signed URL (currently 5 minutes).
• text is truncated to 10 000 characters in the webhook. Fetch the full body via email.self.
• attachments contains metadata only (name, content type, size in bytes). Download the raw email via rawEmailUrl to access attachment content.